apiary.apib

FORMAT: 1A
HOST: https://connection.keboola.com

# Storage API
Storage API provides an interface for sending data to Keboola Connection (KBC). The following are the most
important features of the API:
- Importing CSV data into Table Storage
- Exporting CSV data from Table Storage
- Loading arbitrary files into File Storage
- Managing tables including keys and indexes
- Managing buckets including sharing
- Managing component configurations

The CSV files interchanged with Storage must adhere to the
[RFC4180 Specification](http://tools.ietf.org/html/rfc4180) and must use the `UTF-8` encoding.
The files can be sent uncompressed or gzipped. You can find more information about working
with these files in [our manual](https://help.keboola.com/storage/tables/csv-files/).

For a list of available clients and their features, see the
[Developers Documentation](https://developers.keboola.com/integrate/storage/).
In it you will also find more complex examples of
[working with the API](https://developers.keboola.com/integrate/storage/api/).
This documentation assumes that you are already familiar with the
[Keboola Connection Storage component](https://help.keboola.com/storage/).

## HTTP Response Codes
The response from Storage API will have an
[HTTP status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) that will help
you determine if the request was successful. In case of an error, the HTTP status code
will help you determine the cause of the error. The status codes used by Storage API are
listed in the below tables.

### Success responses

<table>
    <tr>
        <td>200 <code>OK</code></td>
        <td>The request was successful.</td>
    </tr>
    <tr>
        <td>201 <code>Created</code></td>
        <td>The request was successful and a new resource was created.</td>
    </tr>
    <tr>
        <td>202 <code>Accepted</code></td>
        <td>Used for <a href='#introduction/synchronous-and-asynchronous-calls'>Asynchronous tasks</a>. A job resource is returned. The actual result must be obtained in another API call.</td>
    </tr>
    <tr>
        <td>204 <code>No Content</code></td>
        <td>The request was successful but there is nothing to return. Usually used as a response of DELETE requests.</td>
    </tr>
</table>

### Error responses
<table>
    <tr>
        <td>400 <code>Bad Request</code></td>
        <td>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.</td>
    </tr>
    <tr>
        <td>401 <code>Unauthorized</code></td>
        <td>Authentication failed.</td>
    </tr>
    <tr>
        <td>403 <code>Forbidden</code></td>
        <td>You don't have access to the resource.</td>
    </tr>
    <tr>
        <td>404 <code>Not Found</code></td>
        <td>You're asking for something that doesn't exist.</td>
    </tr>
    <tr>
        <td>500 <code>Internal Server Error</code></td>
        <td>Something went wrong. We are sorry, it is our fault and we will make our best to fix it! Feel free to <a href='mailto:suppor@keboola.com'>send us a ticket.</a></td>
    </tr>
    <tr>
        <td>503 <code>Temporary Unavailable</code></td>
        <td>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.
        </td>
    </tr>
</table>


## Authentication
Authentication is done via Storage API **Token**. There are multiple options
for [obtaining a Storage API Token](https://help.keboola.com/storage/tokens/).
The token must be sent as a value of the `X-StorageApi-Token` HTTP header with each API call.

Most API calls work within a *KBC Project*. The project is always derived from the token used for the API call.
So the token includes both authentication and authorization to a single project.

## Synchronous and Asynchronous Calls
Calls that represent potentially long-running actions are performed asynchronously.
These are for example: loading table data, snapshotting, exporting table data, table structure modifications, etc.
All asynchronous calls return the HTTP Response code `202` and a [Job Resource](#reference/jobs).
To obtain the actual result of the call, you have to monitor the job status by
[polling the Job Resource URL](https://developers.keboola.com/integrate/storage/api/import-export/#python-example).

## Partial Response
Some API calls that list objects are returning related resources by default. For example,
the [table list](#reference/tables/create-or-list-tables/tables-in-bucket) also returns
the table bucket properties and table attributes. You can use the `include` parameter
to return only the required resources in the response.

## HTTP headers
Some API calls supports custom http headers.

Supported HTTP headers are:
- `X-StorageApi-Token (string)`: storage api authentication token
- `X-KBC-RunId (string)`: id mainly used to match component run with storage job
- `X-KBC-Backend (json string)`: header used to customize underlying backend configuration. Supported options are `context` and `size` (Supported option are different for each backend). Example: `'{"context":"custom-wlm-group","size":"XL"}'`

# Group Maintenance

## Maintenance Response Example [/v2/storage/]

### Example [GET]
In case the system, or a project is under maintenance, you will receive a response similar to the below one.
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.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 503
    + Headers

            Content-type: application/json
            Retry-After: 559

    + Body

            {
                "status":"maintenance",
                "estimatedEndTime":"2013-05-25T10:30:44+02:00",
                "reason":"Thesystemisdownformaintenance",
            }


# Group Tokens and Permissions
When joining a project, each project administrator is assigned a [*master* token](https://help.keboola.com/storage/tokens/),
which enables them to create other tokens with limited privileges for buckets and components.

Selected of tokens endpoints can be used with `default` for `branch_id` parameter and emulate call endpoint without development branch.
It means that endpoint `GET /v2/storage/tokens/verify` is the same as `GET /v2/storage/branch/default/tokens/verify`.

## Tokens Collection [/v2/storage/tokens]
### List all tokens [GET]
Lists all tokens in the project.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "38",
                    "token": "9eabdd51eaab4040f952e0e6ae6eff03",
                    "description": "",
                    "created": "2012-11-13T16:49:28+0100",
                    "refreshed": "2017-11-13T16:48:28+0100",
                    "uri": "https://connection.keboola.com/v2/storage/tokens/38",
                    "isMasterToken": true,
                    "canManageBuckets": true,
                    "canManageTokens": false,
                    "canReadAllFileUploads": false,
                    "canPurgeTrash": false,
                    "canManageProtectedDefaultBranch": false,
                    "expires": null,
                    "isExpired": false,
                    "isDisabled": false,
                    "dailyCapacity": 5,
                    "bucketPermissions": {
                        "in.c-main": "manage",
                        "out.c-main": "manage",
                        "in.c-ga": "manage"
                    },
                    "admin": {
                        "id": 124,
                        "name": "John Doe",
                        "role": "admin"
                    }
                },
                {
                    "id": "40",
                    "token": "68ab920b621f159f72dcce4ae39a9a0d",
                    "description": "",
                    "created": "2012-11-13T16:49:28+0100",
                    "refreshed": "2017-11-13T16:48:28+0100",
                    "uri": "https://connection-devel.keboola.com/v2/storage/tokens/40",
                    "isMasterToken": false,
                    "canManageBuckets": false,
                    "canManageTokens": false,
                    "canReadAllFileUploads": false,
                    "canPurgeTrash": false,
                    "canManageProtectedDefaultBranch": false,
                    "expires": null,
                    "isExpired": false,
                    "isDisabled": false,
                    "dailyCapacity": 5,
                    "creatorToken": {
                        "id": 1,
                        "description": "dev@keboola.com"
                    },
                    "bucketPermissions": {
                        "in.c-main": "read"
                    },
                    "componentAccess": [
                        "someComponentName"
                    ]
                }
            ]

### List all tokens in Development branch [GET /v2/storage/branch/{branch_id}/tokens]
Lists all tokens in the project - **same as for default branch**.

+ Parameters
    + branch_id (required, number) - Id of the development branch

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "38",
                    "token": "9eabdd51eaab4040f952e0e6ae6eff03",
                    "description": "",
                    "created": "2012-11-13T16:49:28+0100",
                    "refreshed": "2017-11-13T16:48:28+0100",
                    "uri": "https://connection.keboola.com/v2/storage/tokens/38",
                    "isMasterToken": true,
                    "canManageBuckets": true,
                    "canManageTokens": false,
                    "canReadAllFileUploads": false,
                    "canPurgeTrash": false,
                    "canManageProtectedDefaultBranch": false,
                    "expires": null,
                    "isExpired": false,
                    "isDisabled": false,
                    "dailyCapacity": 5,
                    "bucketPermissions": {
                        "in.c-main": "manage",
                        "out.c-main": "manage",
                        "in.c-ga": "manage"
                    },
                    "admin": {
                        "id": 124,
                        "name": "John Doe",
                        "role": "admin"
                    }
                },
                {
                    "id": "40",
                    "token": "68ab920b621f159f72dcce4ae39a9a0d",
                    "description": "",
                    "created": "2012-11-13T16:49:28+0100",
                    "refreshed": "2017-11-13T16:48:28+0100",
                    "uri": "https://connection-devel.keboola.com/v2/storage/tokens/40",
                    "isMasterToken": false,
                    "canManageBuckets": false,
                    "canManageTokens": false,
                    "canReadAllFileUploads": false,
                    "canPurgeTrash": false,
                    "canManageProtectedDefaultBranch": false,
                    "expires": null,
                    "isExpired": false,
                    "isDisabled": false,
                    "dailyCapacity": 5,
                    "creatorToken": {
                        "id": 1,
                        "description": "dev@keboola.com"
                    },
                    "bucketPermissions": {
                        "in.c-main": "read"
                    },
                    "componentAccess": [
                        "someComponentName"
                    ]
                }
            ]

### Create token [POST]
Creates a new token in the project. Note that it is not possible to create a new master token.

If your admin token does not have `canManageTokens` permission, you can only create temporary token with minimal privileges.
In this case, you are allowed to set the `description` and token expiration via `expiresIn` parameter. All other attributes will be ignored.

+ Attributes
    + description (optional) - Token description
    + bucketPermissions[{id_bucket}] (optional) - Permissions for a bucket. Available permissions: `read`, `write`.
    + componentAccess[] (optional) - Grants access for component configurations. Allowed
    values are [valid component IDs](#reference/miscellaneous/api-index/component-list).
    + canManageBuckets (optional, boolean) - Allows full access to all buckets including newly created buckets.
    Overrides `bucketPermissions` settings.
        + Default: false
    + canReadAllFileUploads (optional, boolean) - Allows access to all file uploads. When set to false,
    only files uploaded by the current token are accessible.
        + Default: false
    + canPurgeTrash (optional, boolean) - Allows permanently remove deleted configurations.
        + Default: false
    + expiresIn (optional, number) - Number of seconds until the token expires. If not provided, the token never expires.
    + canManageProtectedDefaultBranch (optional, boolean) - [EXPERIMENTAL] If set to true, the token will have privileged access to default branch of the project. Parameter is implicitly `false` for read-only role. In addition to normal token, requests using this parameter must be authenticated using application token with scope `storage:tokens:create-protected-default-branch-privileged` as well.
    + canCreateJobs (optional, boolean) - [EXPERIMENTAL] If set to true, the token will have privileged to create token with canManageProtectedDefaultBranch. Creation of this type of token is restricted only for projects with `protected-default-branch` feature and for productionManager role.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "description": "my-new-token",
                "bucketPermissions": {
                    "in.c-main": "read"
                },
                "componentAccess": [
                    "keboola.ex-db-mysql"
                ],
                "expiresIn": 60
            }

+ Response 201 (application/json)
    + Body

            {
                "id": "484",
                "token": "75-12d4bfa4995694a1c956e7bb1eea0df5cc53acdb",
                "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,
                "expires": null,
                "isExpired": false,
                "isDisabled": false,
                "dailyCapacity": 5,
                "creatorToken": {
                    "id": 1,
                    "description": "dev@keboola.com"
                },
                "bucketPermissions": {
                    "in.c-main": "read"
                },
                "componentAccess": [
                    "keboola.ex-db-mysql"
                ],
                "expires": "2012-11-13T16:49:28+0100",
                "isExpired": false,
                "isDisabled": false,
                "dailyCapacity": 5
            }

## Token [/v2/storage/tokens/{id_token}]
### Token detail [GET]
Returns all properties of a token. You can obtain the Token Id, for example, using
the [Verify call](#reference/tokens-and-permissions/token/token-verification).

+ Parameters
    + id_token (required, number) - Token Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "id": "44",
                "token": "bdc4ce6a0ea85a2f4313b5b0b1800df3",
                "description": "",
                "created": "2017-11-13T16:48:28+0100",
                "refreshed": "2017-11-13T16:48:28+0100",
                "uri": "https://connection-devel.keboola.com/v2/storage/tokens/44",
                "isMasterToken": false,
                "isBYODB": false,
                "canReadAllFileUploads": false,
                "canPurgeTrash": false,
                "expires": null,
                "isExpired": false,
                "isDisabled": false,
                "dailyCapacity": 5,
                "creatorToken": {
                    "id": 1,
                    "description": "dev@keboola.com"
                },
                "bucketPermissions": [],
                "owner": {
                    "name": "Buckets 5",
                    "id": "58"
                },
                "adminOwner": {
                    "id": 17,
                    "name": "Username",
                    "email": "username@keboola.com"
                }
            }

### Development branch token detail [GET /v2/storage/branch/{branch_id}/tokens/{token_id}]
Returns all properties of a token - **same as for default branch**. You can obtain the Token Id, for example, using
the [Verify call](#reference/tokens-and-permissions/token/token-verification).

+ Parameters
    + branch_id (required, number) - Id of the development branch
    + token_id (required, number) - Token Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "id": "44",
                "token": "bdc4ce6a0ea85a2f4313b5b0b1800df3",
                "description": "",
                "created": "2017-11-13T16:48:28+0100",
                "refreshed": "2017-11-13T16:48:28+0100",
                "uri": "https://connection-devel.keboola.com/v2/storage/tokens/44",
                "isMasterToken": false,
                "isBYODB": false,
                "canReadAllFileUploads": false,
                "canPurgeTrash": false,
                "expires": null,
                "isExpired": false,
                "isDisabled": false,
                "dailyCapacity": 5,
                "creatorToken": {
                    "id": 1,
                    "description": "dev@keboola.com"
                },
                "bucketPermissions": [],
                "owner": {
                    "name": "Buckets 5",
                    "id": "58"
                }
            }

### Update Token [PUT]
Updates Token properties. Beware that all current bucket permissions are replaced. If you want to add new
bucket permissions, don't forget to specify the previous permissions.

+ Attributes
    + description (required) - Token description
    + bucketPermissions[{id_bucket}] (optional) - Permissions for the bucket. Available permissions: `read`, `write`.
    + componentAccess[] (optional) - Grants access for component configurations. Allowed
    values are [valid component IDs](#reference/miscellaneous/api-index/component-list).
    + canReadAllFileUploads (optional, boolean) - Allows access to all file uploads. When set to false,
    only files uploaded by the current token are accessible.
        + Default: false
    + canPurgeTrash (optional, boolean) - Allows permanently remove deleted configurations.
        + Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "description": "New Description",
                "bucketPermissions": {
                    "in.c-main": "write"
                }
            }

+ Response 200 (application/json)
    + Body

            {
                "id": "67319",
                "token": "578-67319-460300c259ec3fcba4b95d1d5c14a8419268bc2b",
                "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,
                "expires": null,
                "isExpired": false,
                "isDisabled": false,
                "dailyCapacity": 5,
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "componentAccess": [],
                "bucketPermissions": {
                    "in.c-main": "write"
                }
            }

### Delete Token [DELETE]
It is possible to delete only the token that is not the master token, you know that in the token detail there is `"isMasterToken": false` and the token that is not used for table triggers.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

## Token Verification [/v2/storage/tokens/verify]
### Token verification [GET]
Checks the token privileges and returns information about the project to which the token belongs (`owner`)
and the associated administrator (`admin`) with organization (if any). If the project is configured with pay as you go billing, `payAsYouGo` section with details is available under `owner` info. This call can be executed by all tokens.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "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,
                "expires": null,
                "isExpired": false,
                "isDisabled": false,
                "isBYODB": false,
                "dailyCapacity": 0,
                "token": "your_token",
                "bucketPermissions": {
                    "in.c-test": "manage",
                },
                "creatorToken": {
                    "id": 1,
                    "description": "dev@keboola.com"
                },
                "componentAccess": [],
                "admin": {
                    "id": 124,
                    "name": "John Doe",
                    "features": [],
                    "isOrganizationMember": true,
                    "role": "admin",
                    "isActivated": false,
                },
                "organization": {
                    "id": 123
                },
                "owner": {
                    "name": "Buckets 5",
                    "id": "58",
                    "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": {
                       "components.jobsParallelism": {
                           "name": "components.jobsParallelism",
                           "value": 10
                       },
                       "goodData.dataSizeBytes": {
                           "name": "goodData.dataSizeBytes",
                           "value": 1000000000
                       },
                       "goodData.demoTokenEnabled": {
                           "name": "goodData.demoTokenEnabled",
                           "value": 1
                       },
                       "goodData.prodTokenEnabled": {
                           "name": "goodData.prodTokenEnabled",
                           "value": 0
                       },
                       "goodData.usersCount": {
                           "name": "goodData.usersCount",
                           "value": 30
                       },
                       "kbc.adminsCount": {
                           "name": "kbc.adminsCount",
                           "value": 10
                       },
                       "kbc.extractorsCount": {
                           "name": "kbc.extractorsCount",
                           "value": 0
                       },
                       "kbc.monthlyProjectPowerLimit": {
                           "name": "kbc.monthlyProjectPowerLimit",
                           "value": 50
                       },
                       "kbc.writersCount": {
                           "name": "kbc.writersCount",
                           "value": 0
                       },
                       "orchestrations.count": {
                           "name": "orchestrations.count",
                           "value": 10
                       },
                       "storage.dataSizeBytes": {
                           "name": "storage.dataSizeBytes",
                           "value": 50000000000
                       },
                       "storage.jobsParallelism": {
                           "name": "storage.jobsParallelism",
                           "value": 10
                       }
                    },
                    "metrics": {
                       "kbc.adminsCount": {
                           "name": "kbc.adminsCount",
                           "value": 2
                       },
                       "orchestrations.count": {
                           "name": "orchestrations.count",
                           "value": 1
                       },
                       "storage.dataSizeBytes": {
                           "name": "storage.dataSizeBytes",
                           "value": 112128
                       },
                       "storage.rowsCount": {
                           "name": "storage.rowsCount",
                           "value": 1036
                       }
                    },
                    "isDisabled": false,
                    "billedMonthlyPrice": null,
                    "dataRetentionTimeInDays": 7,
                    "assignedBackends": [
                        "snowflake"
                    ],
                    "fileStorageProvider": "aws",
                    "payAsYouGo": {
                        "purchasedCredits": 123
                    }
                }
            }

### Development branch token verification [GET /v2/storage/branch/{branch_id}/tokens/verify]
Checks the token privileges and returns information about the project to which the token belongs (`owner`)
and the associated administrator (`admin`) with organization (if any). If the project is configured with pay as you go billing, `payAsYouGo` section with details is available under `owner` info.
This call can be executed by all tokens.
**Same as for default branch.**

+ Parameters
    + branch_id - Id of development branch

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body
            {
                "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,
                "expires": null,
                "isExpired": false,
                "isDisabled": false,
                "isBYODB": false,
                "dailyCapacity": 0,
                "token": "your_token",
                "bucketPermissions": {
                    "in.c-test": "manage",
                },
                "creatorToken": {
                    "id": 1,
                    "description": "dev@keboola.com"
                },
                "componentAccess": [],
                "admin": {
                    "id": 124,
                    "name": "John Doe",
                    "features": [],
                    "isOrganizationMember": true,
                    "role": "admin"
                },
                "organization": {
                    "id": 123
                },
                "owner": {
                    "name": "Buckets 5",
                    "id": "58",
                    "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": {
                       "components.jobsParallelism": {
                           "name": "components.jobsParallelism",
                           "value": 10
                       },
                       "goodData.dataSizeBytes": {
                           "name": "goodData.dataSizeBytes",
                           "value": 1000000000
                       },
                       "goodData.demoTokenEnabled": {
                           "name": "goodData.demoTokenEnabled",
                           "value": 1
                       },
                       "goodData.prodTokenEnabled": {
                           "name": "goodData.prodTokenEnabled",
                           "value": 0
                       },
                       "goodData.usersCount": {
                           "name": "goodData.usersCount",
                           "value": 30
                       },
                       "kbc.adminsCount": {
                           "name": "kbc.adminsCount",
                           "value": 10
                       },
                       "kbc.extractorsCount": {
                           "name": "kbc.extractorsCount",
                           "value": 0
                       },
                       "kbc.monthlyProjectPowerLimit": {
                           "name": "kbc.monthlyProjectPowerLimit",
                           "value": 50
                       },
                       "kbc.writersCount": {
                           "name": "kbc.writersCount",
                           "value": 0
                       },
                       "orchestrations.count": {
                           "name": "orchestrations.count",
                           "value": 10
                       },
                       "storage.dataSizeBytes": {
                           "name": "storage.dataSizeBytes",
                           "value": 50000000000
                       },
                       "storage.jobsParallelism": {
                           "name": "storage.jobsParallelism",
                           "value": 10
                       }
                    },
                    "metrics": {
                       "kbc.adminsCount": {
                           "name": "kbc.adminsCount",
                           "value": 2
                       },
                       "orchestrations.count": {
                           "name": "orchestrations.count",
                           "value": 1
                       },
                       "storage.dataSizeBytes": {
                           "name": "storage.dataSizeBytes",
                           "value": 112128
                       },
                       "storage.rowsCount": {
                           "name": "storage.rowsCount",
                           "value": 1036
                       }
                    },
                    "isDisabled": false,
                    "billedMonthlyPrice": null,
                    "dataRetentionTimeInDays": 7,
                    "assignedBackends": [
                        "snowflake"
                    ],
                    "fileStorageProvider": "aws",
                    "payAsYouGo": {
                        "purchasedCredits": 123
                    }
                }
            }

## Share Token [/v2/storage/tokens/{token_id}/share]
### Share Token [POST]
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
provided email address. The link will expire in 2 hours.

+ Parameters
    + token_id (required, number) - Token Id

+ Attributes
    + recipientEmail (required) - Recipient's email address
    + message (required) - Message for the token recipient

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "recipientEmail": "martin@keboola.com",
                "message": "Hi"
            }

+ Response 204

## Token Refresh [/v2/storage/tokens/{id_token}/refresh]
### Refresh Token [POST]
Use this method to generate a new token value; the old token value will become immediately invalid.
This method can be executed by all tokens.

+ Parameters
    + id_token - A valid token id. You can get it from [Verify call](#reference/tokens-and-permissions/token/token-verification).

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "id": "48",
                "token": "new_token",
                "description": "Master Token",
                "created": "2017-02-13T10:27:50+0100",
                "refreshed": "2017-11-13T16:48:28+0100",
                "uri": "https://connection-devel.keboola.com/v2/storage/tokens/id_token",
                "isMasterToken": false,
                "canReadAllFileUploads": false,
                "canPurgeTrash": false,
                "expires": null,
                "isExpired": false,
                "isDisabled": false,
                "dailyCapacity": 5,
                "creatorToken": {
                    "id": 1,
                    "description": "dev@keboola.com"
                },
                "bucketPermissions": {
                    "in.c-main": "manage",
                    "out.c-main": "manage",
                    "in.c-twitter": "manage"
                }
            }

# Group Miscellaneous

## API Index [/v2/storage]

### Component List [GET /v2/storage?exclude={exclude}]

Use this API call to obtain definitions of all components, services and stack features available in KBC. For more information about
the KBC Component architecture, see the [Developers documentation](https://developers.keboola.com/overview/).

- `?exclude=components` - the `components` field won't be present in a response
- `?exclude=componentDetails` - the `components` field will include only `id`, `name`, `type`, `ico64`, `ico128`,
`features`, `flags`, `description` and `categories` properties for each component

+ Parameters
    + exclude (optional, enum[string]) - Comma-separated list of resources or parts to exclude from response
        + Members
            + components
            + componentDetails

+ Response 200 (application/json)
    + Body

            {
                "api": "storage",
                "documentation": "http://docs.keboola.apiary.io/",
                "version": "v2",
                "components": [
                    {
                        "id": "orchestrator-2",
                        "uri": "https://orchestrator-2.keboola.com/"
                    },
                    {
                        "id": "transformation",
                        "uri": "https://transformation.keboola.com/"
                    }
                ],
                "services": [
                    {
                        "id": "docker-runner",
                        "url": "https:\/\/docker-runner.keboola.com"
                    },
                    {
                        "id": "import",
                        "url": "https:\/\/import.keboola.com"
                    },
                    {
                        "id": "syrup",
                        "url": "https:\/\/syrup.keboola.com"
                    }
                ],
                "features": [
                    "disable-sync-import-data"
                ],
                "urlTemplates": {
                    "orchestrationJob": "\/admin\/projects\/&&projectId&&\/orchestrations\/&&orchestrationId&&\/jobs\/&&jobId&&"
                }
            }

# Group Buckets
[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)
- BigQuery

## Create or List Buckets [/v2/storage/buckets]
### List all buckets [GET /v2/storage/buckets?include={include}]

All buckets are returned.

+ Parameters
    + include (optional, enum[string]) - Comma-separated list of resources to include for each table.
        + Members
            + metadata
            + linkedBuckets

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "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/tables",
                    "backend": "snowflake"
                    "linkedBy": [
                        {
                            "id": "in.c-linked-bucket",
                            "created": "2017-02-13T12:01:05+0100",
                            "project": {
                                "id": 321,
                                "name": "Some Project"
                            }
                        }, {
                            "id": "in.c-another-linked-bucket",
                            "created": "2017-02-13T12:01:05+0100",
                            "project": {
                                "id": 322,
                                "name": "Some Other Project"
                            }
                        }
                    ],
                    "owner": {
                        "id": 123,
                        "name": "Jan Developer",
                        "email": "jan.dev@keboola.com"
                    },
                    "updated": "2024-11-28T13:03:13+0100",
                    "color": null,
                    "isLinkedBucket": false,
                    "backendPath": [
                        "KBC_PRJ_123",
                        "in.c-main"
                    ],
                },
                {
                    "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData",
                    "id": "in.c-organizationData",
                    "name": "c-organizationData",
                    "displayName": "organization",
                    "stage": "in",
                    "description": "Source bucket description",
                    "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData/tables",
                    "backend": "snowflake",
                    "isReadonly": true,
                    "backendPath": [
                        "KBC_PRJ_123",
                        "in.c-main"
                    ],
                    "sourceBucket": {
                        "id": "in.c-main",
                        "name": "c-main",
                        "description": "Organization shared data"
                        "project": {
                            "id": 123,
                            "name": "Project name"
                        }
                    },
                    "owner": null,
                    "updated": "2024-11-28T13:03:13+0100",
                    "color": "#FF0000",
                    "isLinkedBucket": true
                }
            ]

### Create Bucket [POST]
Using this API call, you can either create a new bucket in the project, or you can link an
existing bucket from another project (see below).

+ Attributes
    + name (required) - New bucket name; only alphanumeric characters and underscores are allowed.
    + stage (optional, enum[string]) - Assigns the bucket to one of the stages.
        + Members
            + in
            + out
        + Default: in
    + description (optional) - Bucket description. **deprecated**
    + backend (optional, enum[string]) - Bucket backend type; the default value is determined by the project settings.
        + Members
            + snowflake
            + bigquery
    + displayName (optional) - Bucket displayName, this name is displayed in UI and can be changed anytime; only alphanumeric characters,underscores and dashes are allowed.
    + color (optional) - Bucket color. Accept valid CSS values for colors.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "my-new-bucket",
                "stage": "in",
                "description": "Some Description"
            }

+ Response 201 (application/json)
    + Body

            {
                "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",
                "stage": "in",
                "description": "Some Description",
                "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-my-new-bucket/tables",
                "created": "2017-02-13T12:01:05+0100",
                "lastChangeDate": null,
                "isReadOnly": false,
                "dataSizeBytes": 0,
                "rowsCount": 0,
                "isMaintenance": false,
                "backend": "snowflake",
                "hasExternalSchema": false,
                "databaseName": null,
                "path": "database_name.c-my-new-bucket",
                "sharing": null,
                "bucketSharingAllowed": true,
                "updated": "2024-11-28T13:03:13+0100",
                "color": null,
                "isLinkedBucket": false,
                "backendPath": [
                    "KBC_PRJ_123",
                    "in.c-main"
                ],
            }

### Link Shared Bucket [POST /v2/storage/buckets?async={async}]
Use this API call to create a new bucket which contains 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 it has been
[enabled](#reference/buckets/bucket-sharing/share-bucket) in the source project.

+ Parameters
    + async (optional, boolean) - Share the bucket in a background job.


+ Attributes
    + name (required) - New bucket name; only alphanumeric characters and underscores are allowed.
    + sourceProjectId (required, number) - Id of the source project from which the bucket is being shared
    + sourceBucketId (required) - Id of the bucket being shared
    + stage (optional, enum[string]) - Assigns the bucket to one of the stages.
        + Members
            + in
            + out
        + Default: in

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "organizationData",
                "stage": "in",
                "sourceProjectId": 123,
                "sourceBucketId": "in.c-shared-bucket"
            }

+ Response 201 (application/json)
Synchronous call response (async=false)
    + Body

            {
                "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData",
                "id": "in.c-organizationData",
                "name": "c-organizationData",
                "displayName": "organizationData",
                "stage": "in",
                "description": "Source bucket description",
                "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-organizationData/tables",
                "backend": "snowflake",
                "isReadonly": true,
                "sourceBucket": {
                    "id": "in.c-shared-bucket",
                    "name": "c-shared-bucket",
                    "description": "Organization shared data"
                    "project": {
                        "id": 123,
                        "name": "Project name"
                    }
                },
                "owner": null,
                "updated": "2024-11-28T13:03:13+0100",
                "isLinkedBucket": true,
                "backendPath": [
                    "KBC_PRJ_123",
                    "in.c-main"
                ],
            }

+ Response 202
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketLink",
                "operationParams": {
                    "params": {
                        "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": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Register bucket [POST /v2/storage/buckets/register]
**EXPERIMENTAL**

Use this API call to create a new bucket from existing resource (schema or DB - depends on backend). Available for **Snowflake** and **BigQuery** backends only

+ Attributes
    + name (required) - New bucket name; only alphanumeric characters and underscores are allowed.
    + stage (optional, enum[string]) - Assigns the bucket to one of the stages.
        + Members
            + in
            + out
        + Default: in
    + description (optional) - Bucket description.
    + backend (optional, enum[string]) - Bucket backend type; the default value is determined by the project settings.
        + Members
            + snowflake
            + bigquery
    + displayName (optional) - Bucket displayName, this name is displayed in UI and can be changed anytime; only alphanumeric characters,underscores and dashes are allowed.
    + path (required, array) - Path to the schema. On SNFLK ['database-name','schema-name'], BigQuery ['projectId', 'location', 'exchangerName', 'listingName']
    + isSnowflakeSharedDatabase (optional, boolean) - Flag if external bucket uses Snowflake Secure Data Share feature

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "organizationData",
                "displayName": "organization-members",
                "stage": "in",
                "description": "my bucket",
                "backend": "snowflake",
                "path": ["DATABASE", "SCHEMA"]
            }

+ Response 202
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketRegister",
                "operationParams": {
                    "params": {
                        "bucketName": "organizationData",
                        "displayName": "organizationData",
                        "bucketStage": "in",
                        "path": ["DATABASE", "SCHEMA"],
                        "devBranchId": 4230,
                        "queue": "main"
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Register bucket - guide [GET /v2/storage/buckets/register-guide?backend={backend}&path={path}]
**EXPERIMENTAL**

Returns a guide on how exactly you should register the external bucket. The text is Markdown formatted. Available for **Snowflake** and **BigQuery** backend only

+ Parameters
    + backend (optional, enum[string]) - Bucket backend type; the default value is determined by the project settings.
        + Members
            + snowflake
            + bigquery
    + path (required, array[string]) - Path to the schema. For Snowflake backend it's in a format ['database-name','schema-name'], for BigQuery ['dataset-name']
    + isSnowflakeSharedDatabase (optional, boolean) - render guide for Snowflake shared database

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {"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"}


## Manage Bucket [/v2/storage/buckets/{bucket_id}?include={include}]
### Bucket Detail [GET]
Obtains information about a bucket.

+ Parameters
    + bucket_id (required) - Bucket Id
    + include (optional, enum[string]) - Comma-separated list of resources to include for each table.
        + Members
            + `metadata` - each table will include list of it's metadata
            + `columns` - each table will include list of it's columns
            + `columnMetadata` - each table will include list of it's columns metadata
            + `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. Works across projects for linked buckets

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-ga",
                "id": "in.c-ga",
                "name": "c-ga",
                "displayName": "ga",
                "stage": "in",
                "description": "Google Analytics",
                "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-ga/tables",
                "backend": "snowflake",
                "hasExternalSchema": false,
                "databaseName": null,
                "path": "database_name.c-ga",
                "linkedBy": [
                    {
                        "id": "in.c-linked-bucket",
                        "created": "2017-02-13T12:01:05+0100",
                        "project": {
                            "id": 321,
                            "name": "Some Project"
                        }
                    }, {
                        "id": "in.c-another-linked-bucket",
                        "created": "2017-02-13T12:01:05+0100",
                        "project": {
                            "id": 322,
                            "name": "Some Other Project"
                        }
                    }
                ],
                "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"
                    }
                ],
                "owner": {
                    "id": 123,
                    "name": "Jan Developer",
                    "email": "jan.dev@keboola.com"
                },
                "bucketSharingAllowed": true,
                "updated": "2024-11-28T13:03:13+0100",
                "isLinkedBucket": false,
                "backendPath": [
                    "KBC_PRJ_123",
                    "in.c-main"
                ],
            }

### Bucket Update [PUT /v2/storage/buckets/{bucket_id}/?async={async}]
Update an existing bucket

+ Parameters
    + bucket_id (required) - Bucket Id
    + async (optional, boolean) - Updates the bucket in a background job. This is useful if updates takes too much time and times out.

+ Attributes
    + displayName (required, string) - Bucket displayName, this name is displayed in UI and can be changed anytime; only alphanumeric characters,underscores and dashes are allowed.
    + color (optional) - Bucket color. Accept valid CSS values for colors.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "displayName": "my-display-name-for-bucket",
                "color": "#00FF00"
            }

+ Response 200 (application/json)
Synchronous call response (async=false)

    + Body

            {
                "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-my-bucket",
                "id": "in.c-my-bucket",
                "name": "c-my-bucket",
                "displayName": "my-display-name-for-bucket",
                "stage": "in",
                "description": "Some Description",
                "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-my-bucket/tables",
                "created": "2017-02-13T12:01:05+0100",
                "lastChangeDate": null,
                "isReadOnly": false,
                "dataSizeBytes": 0,
                "rowsCount": 0,
                "isMaintenance": false,
                "backend": "snowflake",
                "sharing": null,
                "bucketSharingAllowed": true,
                "owner": null,
                "updated": "2024-11-28T13:03:13+0100",
                "color": "#00FF00",
                "backendPath": [
                    "KBC_PRJ_123",
                    "in.c-main"
                ],
            }
+ Response 202
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)

    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketDelete",
                "operationParams": {
                    "params": {
                        "idBucket": 123,
                        "force": true
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Bucket Refresh [PUT /v2/storage/buckets/{bucket_id}/refresh]
**EXPERIMENTAL**

Refresh external bucket. For **Snowflake** and **Bigquery** backends only. If database object (DB, Schema...) isn't available anymore (was deleted or revoked), the bucket in Storage will be deleted.


+ Parameters
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)

    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketRefresh",
                "operationParams": {
                    "params": {
                        "idBucket": 123,
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }


### Schedule bucket refresh [POST /v2/storage/branch/{branch_id}/buckets/{bucket_id}/scheduled-tasks/refresh]

**EXPERIMENTAL**

Schedule external bucket refresh to given time or repeating period defined by cron expression.

+ Parameters
    + branch_id (required) - Branch Id
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            Content-Type: application/json
            X-StorageApi-Token: your_token

    + Body

            {
                "cronExpression": "42 13 * * *"
            }

+ Response 201 (application/json)

    Return scheduled task data.

    + Body

            {
                "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"
            }

### Bucket Tables Information Refresh [POST /v2/storage/branch/{branch_id}/buckets/{bucket_id}/refresh-tables-info]
Refresh tables information in bucket. For **Snowflake** backend only. Aliases with source table in the defined bucket are also refreshed. If alias in the discussed bucket has source table in another bucket, it won't be refreshed.


+ Parameters
    + branch_id (required) - Branch Id
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)

    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketRefreshTablesInformation",
                "operationParams": {
                    "params": {
                        "idBucket": 123,
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Drop Bucket [DELETE /v2/storage/buckets/{bucket_id}/?force={force}&async={async}]
Deletes a bucket from the project. In the default mode, only empty buckets can be deleted.
Use the optional `force` parameter to delete all bucket content too.

+ Parameters
    + bucket_id (required) - Bucket Id
    + force (optional, boolean) - Drops all tables and aliases. Tables must not have any dependencies (aliases, etc.).
    + async (optional, boolean) - Drops the bucket in a background job. This is useful if dropping takes too much time and times out.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204
Synchronous call response (async=false)
    + Body

+ Response 202
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketDelete",
                "operationParams": {
                    "params": {
                        "idBucket": 123,
                        "force": true
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Bucket Owner detail [GET /v2/storage/buckets/{bucket_id}/owner]
Return information about current bucket owner.

+ Parameters
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200
    + Body

        {
            "id": 123,
            "name": "Dev",
            "email": "dev@keboola.com"
        }

+ Response 404

### Bucket Owner update [POST /v2/storage/buckets/{bucket_id}/owner]
Update information about current bucket owner.

+ Parameters
    + bucket_id (required) - Bucket Id
    + id (optional, boolean) - Project Admin ID. ID or email is required.
    + email (optional, boolean) - Project Admin email. ID or email is required.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200

+ Response 404

## Bucket Sharing

### Share Bucket To Organization [POST /v2/storage/buckets/{bucket_id}/share-organization]
[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **update 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 operations is available only for organization administrators.
+ Parameters
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketShareToOrganization",
                "operationParams": {
                    "params": {
                        "queue": "main"
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Share Bucket To Organization Project [POST /v2/storage/buckets/{bucket_id}/share-organization-project]
[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **update 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 operations is available only for organization administrators.
+ Parameters
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketShareToOrganizationProject",
                "operationParams": {
                    "params": {
                        "queue": "main"
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Share Bucket To Projects [POST /v2/storage/buckets/{bucket_id}/share-to-projects]
[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **update sharing** for this bucket to a specific set of projects in the organization.
All users who are member of one of the targeted projects will be able to link to this bucket from that specific project.
This operations is available only for organization administrators.

+ Parameters
    + bucket_id (required) - Bucket Id

+ Attributes
    + targetProjectIds[] (required, array) - array of projects id

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token
    + Body

            {
                "targetProjectIds": [
                    "1",
                    "2",
                    "3"
                ]
            }

+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketShareToProjects",
                "operationParams": {
                    "params": {
                        "targetProjectIds": [
                          1
                        ],
                        "queue": "main"
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Share Bucket To Users [POST /v2/storage/buckets/{bucket_id}/share-to-users]
[Enables sharing](https://help.keboola.com/storage/buckets/sharing/) or **update 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 operations is available only for organization administrators.

+ Parameters
    + bucket_id (required) - Bucket Id

+ Attributes
    + targetUsers[] (required, array) - array of users id or user emails. Users must be member of at least one project in the organization.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token
    + Body

            {
                "targetUsers": [
                    "dev@keboola.com",
                    "dev2@keboola.com",
                    "dev3@keboola.com"
                ]
            }

+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketShareToAdmins",
                "operationParams": {
                    "params": {
                        "targetUsers": [
                          1
                        ],
                        "queue": "main"
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Change Bucket Sharing [PUT /v2/storage/buckets/{bucket_id}/share]
Change [sharing type](https://help.keboola.com/storage/buckets/sharing/#sharing-type) of a bucket.
This operations is available only for organization administrators.


+ Parameters
    + bucket_id (required) - Bucket Id

+ Attributes
    + sharing (required, enum[string]) - Sharing type
        + Members
            + `organization` - Bucket is shared to organization. Any organization member will be able to link to this bucket from any project within the organization.
            + `organization-project` - Bucket is shared to organization. Any member of a project within the organization will be able to link to this bucket from their project.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketShareUpdate",
                "operationParams": {
                    "params": {
                        "sharingType": "organization-project",
                        "queue": "main"
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Stop Bucket Sharing [DELETE /v2/storage/buckets/{bucket_id}/share]
Disables sharing of a bucket. A bucket must not be linked to other projects.
To unshare an already linked bucket, you have to delete the links first - use the
[Drop Bucket](#reference/buckets/manage-bucket/drop-bucket) in the linking project.
This operations is available only for organization administrators.

+ Parameters
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketRemoveShare",
                "operationParams": {
                    "params": {
                        "queue": "main"
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }


### Delete Bucket Listing [DELETE /v2/storage/buckets/{bucket_id}/listing]
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.

+ Parameters
    + bucket_id (required) - Bucket Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketListingDelete",
                "operationParams": {
                    "params": {
                        "queue": "main"
                    }
                },
                "createdTime": "2026-04-24T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }


### Force unlink a bucket from a project  [DELETE /v2/storage/buckets/{bucket_id}/links/{linkedProjectId}?async={async}]

When bucket is shared and someone links it, it effectively prevents the owner of the data from revoking the share.
When 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.

**Note:** You may break some workflows in the project that linked the data by force unlinking the bucket.

+ Parameters
    + bucket_id (required) - Bucket Id
    + linkedProjectId (required, number) - id of project where the bucket is linked
    + async (optional, boolean) - Unlinks the bucket in a background job. This is useful if dropping takes too much time and times out.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204
Synchronous call response (async=false)
    + Body
+ Response 202
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "bucketForceUnlink",
                "operationParams": {
                    "params": {
                        "linkedIdBucket": 123,
                        "linkedIdProject": 321,
                        "async": true
                    }
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "roman.bracinik@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

## List Shared Buckets [/v2/storage/shared-buckets?include={include}]
Lists buckets which may be shared to the project.

### Shared buckets list [GET]

+ Parameters
    + include (optional) - Comma-separated list of resources to include for each table. Available resources: 'metadata'.
        + Default: ''

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "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",
                    "project": {
                        "id": 123,
                        "name": "Project name"
                    },
                    "tables": [
                        {
                            "id": "in.c-main.languages",
                            "name": "languages"
                            "displayName": "languages-display-name"
                        }
                    ],
                    "color" : null,
                    "sharingParameters": [],
                    "sharedBy": {
                        "id": 5,
                        "name": "dev@keboola.com",
                        "date": "2020-02-03T14:58:29+0100"
                    }
                    "owner": null,
                    "updated": "2024-11-28T13:03:13+0100"
                }
            ]

# Group Tables

## Create or List Tables [/v2/storage/buckets/{bucket_id}/tables]

### Create new table from CSV file [POST]

***DEPRECATED**, use [Create table asynchronously](#reference/tables/create-table-asynchronously/create-new-table-from-csv-file-asynchronously) instead.*

Creates a new table in a bucket. The CSV file must follow the [RFC 4180 Specification](https://tools.ietf.org/html/rfc4180).
More information about the requirements can be found in the [Manual](https://help.keboola.com/storage/tables/csv-files/).
Column names are extracted from the CSV file header; spaces and any other special characters in column names are
replaced with an underscore. This API call should be used only for tables which can be safely transferred in a single HTTP request; for large
tables use the [asynchronous call](#reference/tables/create-table-asynchronously/create-new-table-from-csv-file-asynchronously).

+ Parameters
    + bucket_id (required) - Bucket Id

+ Attributes
    + name (required) - New table name
    + data (required) - 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`.
    + delimiter (optional) - Field delimiter used in the CSV file. The default value is ','.  Use '\t' or type the char for the tabulator.
    + enclosure (optional) - Field enclosure used in the CSV file. The default value is '"'. (Note: you can specify either `enclosure` or `escapedBy` parameter, not both.)
    + escapedBy (optional) - Escape character used in the CSV file. The default value is an empty value - no escape character is used. (Note: you can specify either `enclosure` or `escapedBy` parameter, not both.)
    + primaryKey (optional) - Primary key of the table. If the primary key is set, updates can be done on the table. See the CSV incremental import. The primary key can be also composed by multiple columns; the columns must be separated by a comma.

+ Request (multipart/form-data)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            ------WebKitFormBoundaryqPuY88H6m4oIp6zq
            Content-Disposition: form-data; name="name"
            my_table_name
            ------WebKitFormBoundaryqPuY88H6m4oIp6zq
            Content-Disposition: form-data; name="data"; filename="my_table_name.csv"
            Content-Type: application/octet-stream
            file_content
            ------WebKitFormBoundaryqPuY88H6m4oIp6zq
            Content-Disposition: form-data; name="delimiter"
            ,
            ------WebKitFormBoundaryqPuY88H6m4oIp6zq
            Content-Disposition: form-data; name="enclosure"
            "
            ------WebKitFormBoundaryqPuY88H6m4oIp6zq--

+ Response 201 (application/json)
    + Body

            {
                "uri": "https://connection.keboola.com/v2/storage/tables/in.c-main.languages",
                "id": "in.c-main.languages",
                "name": "languages",
                "displayName": "languages-displayName",
                "gdName": "languages",
                "created": "2012-07-23 09:51:45",
                "lastImportDate": null,
                "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/tables"
                }
            }

### Tables in bucket [GET /v2/storage/buckets/{bucket_id}/tables?include={include}]
Lists tables in a given bucket.

+ Parameters
    + bucket_id (required) - Bucket Id
    + include (optional, enum[string]) - Comma-separated list of resources to include for each table
        + Members
            + 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. Works across projects for linked buckets
        + Default: metadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "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",
                    "transactional": false,
                    "primaryKey": [],
                    "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,
                    "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"
                            }
                        ]
                    }
                },
                {
                    "uri": "https://connection.keboola.com/v2/storage/tables/in.c-keboola-ex-db-snowflake-528221294.datatypes-alias",
                    "id": "in.c-keboola-ex-db-snowflake-528221294.datatypes-alias",
                    "name": "datatypes-alias",
                    "transactional": false,
                    "primaryKey": [],
                    "created": "2019-08-14T11:43:17+0200",
                    "lastImportDate": "2019-08-12T21:16:41+0200",
                    "lastChangeDate": "2019-08-12T21:16:41+0200",
                    "rowsCount": 2,
                    "dataSizeBytes": 1024,
                    "isAlias": true,
                    "isAliasable": true,
                    "isTyped": false,
                    "timestampType": "MANAGED",
                    "tableType": "table",
                    "path": "kbc_578.c-keboola-ex-db-snowflake-528221294.datatypes-alias",
                    "sourceTable": {
                        "id": "in.c-keboola-ex-db-snowflake-528221294.datatypes",
                        "uri": "https://connection.keboola.com/v2/storage/tables/in.c-keboola-ex-db-snowflake-528221294.datatypes",
                        "isAlias": false,
                        "project": {
                            "id": 578,
                            "name": "Some source project"
                        },
                        "metadata": [
                            {
                                "id": "206180829",
                                "key": "KBC.description",
                                "value": "Table containing data types",
                                "provider": "user",
                                "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"
                                }
                            ]
                        }
                    },
                    "aliasColumnsAutoSync": true,
                    "metadata": [],
                    "columnMetadata": []
                }
            ]

## Create Table Definition [/v2/storage/buckets/{bucket_id}/tables-definition]

### Create new table definition [POST]

Creates a table with typed columns. *Snowflake|BigQuery only.*

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

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

+ Parameters
    + bucket_id (required) - The bucket Id

+ Attributes
    + name (required) - New table name
    + primaryKeysNames[] (string) - Has to be subset of column names and not nullable.
    + timestampType (optional, enum[string]) - Standard storage tables internally manage a _timestamp column which is updated on each import with the current timestamp. This option allows to prevent internal _timestamp column creation.
        + Members
            + MANAGED
            + NONE
        + Default: MANAGED
    + columns[] (required) - definition of table columns
       + name (required, string) - column name
       + definition (object) - column settings
            + type (string) - datatype of this column, choose build in types for used backend [Snowflake](https://docs.snowflake.com/en/sql-reference/intro-summary-data-types.html), [BigQuery](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)
            + length (string) - optional, default: depends on type
            + nullable (boolean) - optional, default: true (when column is part of primary key and nullable is not set default will be set to false)
            + default (string) - optional, default value for column
       + basetype (enum[string]) - base datatype of this column, will be converted to backend specific types
            + Members
                + BOOLEAN
                + DATE
                + FLOAT
                + INTEGER
                + NUMERIC
                + STRING
                + TIMESTAMP
    + timePartitioning - BigQuery only [(documentation)](https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#timepartitioning)
        + type (required, enum[string])
            + Members
                + DAY
                + HOUR
                + MONTH
                + YEAR
        + field (string) - has to be subset of column names
        + expirationMs (number) - optional
    + clustering - BigQuery only [(documentation)](https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#clustering)
        + fields[] (required) - has to be subset of column names
    + rangePartitioning - BigQuery only [(documentation)](https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#rangepartitioning)
        + field (required,string) - has to be subset of column names
        + range (required) - has to be subset of column names
            + start (required, number)
            + end (required, number)
            + interval (required, number)
+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "my-new-table",
                "primaryKeysNames": [
                    "id"
                ],
                "columns": [
                    {
                        "name": "id",
                        "definition": {
                            "type": "INT"
                        }
                    },
                    {
                        "name": "name",
                        "definition": {
                            "type": "NVARCHAR"
                        }
                    }
                ],
                "distribution": {
                    "type": "HASH",
                    "distributionColumnsNames": [
                        "id"
                    ]
                },
                 "index": {
                     "type": "CLUSTERED INDEX",
                     "indexColumnsNames": [
                         "id"
                     ]
                 }
            }

+ Response 202 (application/json)

        {
            "id": 356,
            "status": "waiting",
            "url": "https:\/\/localhost:8700\/v2\/storage\/jobs\/356",
            "tableId": null,
            "operationName": "tableDefinitionCreate",
            "operationParams": {
                "name": "my-new-table",
                "primaryKeysNames": [
                    "id"
                ],
                "columns": [
                    {
                        "name": "id",
                        "definition": {
                            "type": "INT",
                            "nullable": true
                        }
                    },
                    {
                        "name": "name",
                        "definition": {
                            "type": "NVARCHAR",
                            "nullable": true
                        }
                    }
                ],
                "distribution": {
                    "type": "HASH",
                    "distributionColumnsNames": [
                        "id"
                    ]
                },
                "index": {
                    "type": "CLUSTERED INDEX",
                    "indexColumnsNames": [
                        "id"
                    ]
                }
                "queue": "main"
            },
            "createdTime": "2021-05-24T11:09:47+0200",
            "startTime": null,
            "endTime": null,
            "runId": "5107",
            "results": null,
            "creatorToken": {
                "id": "553",
                "description": "devel+test-backend_admin@keboola.com"
            },
            "metrics": {
                "inCompressed": false,
                "inBytes": 0,
                "inBytesUncompressed": 0,
                "outCompressed": false,
                "outBytes": 0,
                "outBytesUncompressed": 0
            }
        }

## Update Definition

### Update Column Definition [PUT /v2/storage/tables/{table_id}/columns/{column_name}/definition]

Updates a column of a table with typed columns. *Snowflake, BigQuery only.*

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

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

Supported alterations:
| | Snowflake | BigQuery |
| --- | --- | --- |
| Add default| ❌ | ✅ |
| Change default |  ❌ | ✅ |
| Drop default | ✅ | ✅ |
| Set as nullable | ✅ | ✅ |
| Set as required | ✅ | ❌ |
| Change type | ❌ | ❌ |
| Increase the length of a text column | ✅ | ✅ |
| Decrease the length of a text column | ❌ | ❌ |
| Increase the precision of a numeric column | ✅ | ✅ |
| Decrease the precision of a numeric column | ❌ | ❌ |
| Change the scale of a numeric column | ❌ | ✅ |


+ Parameters
    + table_id (required) - The table Id
    + column_name (required) - The column name

+ Attributes
    + length (string) - optional, supports numeric value for all columns (e.g. `12`) and complex length for numeric columns (e.g. `12,2`)
    + nullable (boolean) - optional, on BigQuery operation "set as required" (nullable=true -> nullable=false) is not allowed
    + default (string) - optional, default value for column, null unsets default value

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "length": "10",
                "nullable": false,
                "default": null
            }

+ Response 202 (application/json)

        {
            "id": 2866,
            "status": "waiting",
            "url": "https:\/\/localhost:8700\/v2\/storage\/jobs\/2866",
            "tableId": "in.c-API-tests-cb373d9e306e38e68f1c5824bbb3f9b256cc1077.table-cb373d9e306e38e68f1c5824bbb3f9b256cc1077",
            "operationName": "tableColumnDefinitionUpdate",
            "operationParams": {
                "queue": "main",
                "branchId": 18,
                "columnName": "short_int",
                "columnDefinition": {
                    "length": "10",
                    "nullable": false,
                    "removeDefault": true
                }
            },
            "createdTime": "2024-02-13T12:48:44+0100",
            "startTime": null,
            "endTime": null,
            "runId": "5747",
            "results": null,
            "creatorToken": {
                "id": "51",
                "description": "devel-tests+test-backend_admin@keboola.com"
            },
            "metrics": {
                "inCompressed": false,
                "inBytes": 0,
                "inBytesUncompressed": 0,
                "outCompressed": false,
                "outBytes": 0,
                "outBytesUncompressed": 0
            }
        }

## Pull table from default branch to dev branch [/v2/storage/branch/{branch_id}/tables/{table_id}/pull]

### Pull table from default branch to dev branch [POST]

**EXPERIMENTAL**

Pull table from default branch to dev branch with all data and metadata, if table already exists in dev branch, it will be overwritten.

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

+ Parameters
    + table_id (required) - The table string Id
    + branch_id - Id of development branch

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

+ Response 202 (application/json)

        {
            "id": 356,
            "status": "waiting",
            "url": "https:\/\/localhost:8700\/v2\/storage\/jobs\/356",
            "tableId": in.c-bucket.production-table-1,
            "operationName": "devBranchTablePull",
            "operationParams": {
                "sourceBranchId": 10,
                "targetBranchId": 11
            },
            "createdTime": "2021-05-24T11:09:47+0200",
            "startTime": null,
            "endTime": null,
            "runId": "5107",
            "results": null,
            "creatorToken": {
                "id": "553",
                "description": "devel+test-backend_admin@keboola.com"
            },
            "metrics": {
                "inCompressed": false,
                "inBytes": 0,
                "inBytesUncompressed": 0,
                "outCompressed": false,
                "outBytes": 0,
                "outBytesUncompressed": 0
            }
        }

## Create Table Asynchronously [/v2/storage/buckets/{bucket_id}/tables-async]

### Create new table from CSV file asynchronously [POST]

The method of creating a table asynchronously should be used for larger imports (everything with 100 lines and more).
The create request is created and added to a queue, the job resource url for status polling is returned.

+ Parameters
    + bucket_id (required) - The bucket Id

+ Attributes(CreateTableDefinitionAsyncFile)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "dataFileId": 234,
                "name": "table_name",
                "delimiter": ",",
                "enclosure": "\""
            }

+ Response 202 (application/json)

        {
            "id": 11,
            "status": "waiting",
            "url": "https://connection.keboola.com/v2/storage/jobs/11",
            "operationName": "tableCreate",
            "operationParams": {
                "params": {
                    "enclosure": "\"",
                    "delimiter": ",",
                    "escapedBy": "",
                },
                "source": {
                    "fileId": "234",
                    "type": "file"
                }
            },
            "createdTime": "2013-05-31T16:11:05+0200",
            "startTime": null,
            "endTime": null,
            "runId": null,
            "results": null,
            "creatorToken": {
                "id": "27978",
                "description": "ondrej.popelka@keboola.com"
            },
            "metrics": {
                "inCompressed": false,
                "inBytes": 0,
                "inBytesUncompressed": 0,
                "outCompressed": false,
                "outBytes": 0,
                "outBytesUncompressed": 0
            }
        }

### Create new table from snapshot asynchronously [POST]

The method of creating a table asynchronously should be used for larger imports (everything with 100 lines and more).
The create request is created and added to a queue, the job resource url for status polling is returned.

+ Parameters
    + bucket_id (required) - The bucket Id

+ Attributes(CreateTableDefinitionAsyncSnapshot)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "snapshotId": 234,
                "name": "table_name",
                "delimiter": ",",
                "enclosure": "\""
            }

+ Response 202 (application/json)

        {
            "id": 11,
            "status": "waiting",
            "url": "https://connection.keboola.com/v2/storage/jobs/11",
            "operationName": "tableCreate",
            "operationParams": {
                "params": {
                    "enclosure": "\"",
                    "delimiter": ",",
                    "escapedBy": "",
                },
                "source": {
                    "snapshotId": 234,
                    "type": "snapshot"
                }
            },
            "createdTime": "2013-05-31T16:11:05+0200",
            "startTime": null,
            "endTime": null,
            "runId": null,
            "results": null,
            "creatorToken": {
                "id": "27978",
                "description": "ondrej.popelka@keboola.com"
            },
            "metrics": {
                "inCompressed": false,
                "inBytes": 0,
                "inBytesUncompressed": 0,
                "outCompressed": false,
                "outBytes": 0,
                "outBytesUncompressed": 0
            }
        }

### Create new table from workspace asynchronously [POST]

The method of creating a table asynchronously should be used for larger imports (everything with 100 lines and more).
The create request is created and added to a queue, the job resource url for status polling is returned.

+ Parameters
    + bucket_id (required) - The bucket Id

+ Attributes(CreateTableDefinitionAsyncWorkspace)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "dataWorkspaceId": 234,
                "dataObject": "84353",
                "name": "table_name",
                "delimiter": ",",
                "enclosure": "\""
            }

+ Response 202 (application/json)

        {
            "id": 11,
            "status": "waiting",
            "url": "https://connection.keboola.com/v2/storage/jobs/11",
            "operationName": "tableCreate",
            "operationParams": {
                "params": {
                    "enclosure": "\"",
                    "delimiter": ",",
                    "escapedBy": "",
                },
                "source": {
                    "workspaceId": 234,
                    "dataObject": "84353",
                    "tableName": "84353",
                    "type": "workspace"
                }
            },
            "createdTime": "2013-05-31T16:11:05+0200",
            "startTime": null,
            "endTime": null,
            "runId": null,
            "results": null,
            "creatorToken": {
                "id": "27978",
                "description": "ondrej.popelka@keboola.com"
            },
            "metrics": {
                "inCompressed": false,
                "inBytes": 0,
                "inBytesUncompressed": 0,
                "outCompressed": false,
                "outBytes": 0,
                "outBytesUncompressed": 0
            }
        }

### Create new table from time travel asynchronously [POST]

Supported by Snowflake and BigQuery, BigQuery doesn't support primary keys so if you create a table using time travel for BigQuery backend the new table won't get primary keys.

The method of creating a table asynchronously should be used for larger imports (everything with 100 lines and more).
The create request is created and added to a queue, the job resource url for status polling is returned.

+ Parameters
    + bucket_id (required) - The bucket Id

+ Attributes(CreateTableDefinitionAsyncTimeTravel)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "sourceTableId": "234",
                "name": "table_name",
                "timestamp": "2022-08-01 12:00:00+0200"
            }


+ Response 202 (application/json)

        {
            "id": 11,
            "status": "waiting",
            "url": "https://connection.keboola.com/v2/storage/jobs/11",
            "operationName": "tableCreate",
            "operationParams": {
                "params": {
                    "enclosure": "\"",
                    "delimiter": ",",
                    "escapedBy": "",
                },
                "source": {
                    "sourceTableId": "234",
                    "destinationTableName": "table_name",
                    "timestamp": "2022-08-01 12:00:00+0200",
                    "type": "timeTravel"
                }
            },
            "createdTime": "2013-05-31T16:11:05+0200",
            "startTime": null,
            "endTime": null,
            "runId": null,
            "results": null,
            "creatorToken": {
                "id": "27978",
                "description": "ondrej.popelka@keboola.com"
            },
            "metrics": {
                "inCompressed": false,
                "inBytes": 0,
                "inBytesUncompressed": 0,
                "outCompressed": false,
                "outBytes": 0,
                "outBytesUncompressed": 0
            }
        }

## Load Data [/v2/storage/tables/{table_id}/import]

### Load data from csv file to prepared table [POST]

 **This method of import is DEPRECATED**, please use [asynchronous import](#reference/tables/load-data-asynchronously).

 Each CSV table should contain a header with column names; all columns present in the table must be also present in the CSV file, new columns not present in the table are created. One of the `data` and `dataString`  attributes must be provided.
 The CSV file can be raw or gzipped. Gzipped files must have the extension .gz.

+ Attributes
    + data (optional) - Multipart CSV file upload
    + dataString (optional) - CSV as a string in the request body
    + incremental (optional, boolean) - If `incremental` is a non-zero value, the import adds data to the existing data in the table. If `incremental` is 0, the target table will be truncated before the import.
    + delimiter (optional) - Field delimiter used in the CSV file. The default value is ','.  Use '\t' or type the tab char for the tabulator.
    + enclosure (optional) - Field enclosure used in the CSV file. The default value is '"'.
    + columns[] (optional) - List of columns present in the CSV file; the first line of the file will not be treated as a header!
    + withoutHeaders (optional, boolean) - The CSV file doesn't contain headers, columns are matched by their order. If this option is used, columns option is ignored.


+ Request (multipart/form-data; boundary=----WebKitFormBoundaryU2xN082HVaIRptvd)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            ------WebKitFormBoundaryU2xN082HVaIRptvd
            Content-Disposition: form-data; name="incremental"
            0
            ------WebKitFormBoundaryU2xN082HVaIRptvd
            Content-Disposition: form-data; name="data"; filename="tw_accounts.csv"
            Content-Type: application/octet-stream
            file_content
            ------WebKitFormBoundaryU2xN082HVaIRptvd
            Content-Disposition: form-data; name="delimiter"
            ,
            ------WebKitFormBoundaryU2xN082HVaIRptvd
            Content-Disposition: form-data; name="enclosure"
            "
            ------WebKitFormBoundaryU2xN082HVaIRptvd

+ Response 200 (application/json)

            {
                "status": "ok",
                "warnings": []
            }


## Load data asynchronously [/v2/storage/tables/{table_id}/import-async]

The method of asynchronous importing should be used for larger imports (everything with 100 lines and more).
The import request is created and added to a queue; the job resource url for status polling is returned.
Asynchronous imports requested on the same table will be serialized.

### Import data from CSV file asynchronously [POST]

The actual data must be provided in the following attributes:
- **dataFileId**

An imported file can be sliced into multiple chunks; the conditions described in [File Uploads](#reference/files) must be satisfied.
The CSV file can be raw or gzipped. Gzipped files must have the extension `.gz`. A typical asynchronous import negotiation consists of these steps:

1. Upload a CSV file using [File Upload](#reference/files).
2. Submit an [asynchronous import request](#reference/tables/load-data-asynchronously/imports-data-from-csv-file-asynchronously) with `dataFileId` set to the File ID returned in the previous step.
3. Poll job resource returned in the previous step until the `status` is `success` or `error`.

Further information can be found in the [Developers Documentation](https://developers.keboola.com/integrate/storage/api/import-export/).

+ Parameters
    + table_id (required) - Target table ID

+ Attributes
    + dataFileId (required, number) - ID of the file stored in [File Uploads](#reference/files); all gzipped and sliced files are supported.
    + incremental (optional, boolean) - If `incremental` is a non-zero value, the import adds data to the existing data in the table. If `incremental` is `false`, the target table will be truncated before the import.
    + delimiter (optional, string) - Field delimiter used in the CSV file. The default value is `,`.  Use '\t' or type the tab char for tabulator.
    + enclosure (optional, string) - Field enclosure used in the CSV file. The default value is `"`. (Note: you can specify either `enclosure` or `escapedBy` parameter, not both.)
    + escapedBy (optional, string) - Escape character used in the CSV file. The default value is an empty value - no escape character is used. (Note: you can specify either `enclosure` or `escapedBy` parameter, not both.)
    + columns[] (optional, string) - List of columns present in the CSV file; the first line of the file will not be treated as a header!
    + withoutHeaders (optional, boolean) - Indicates that the CSV file does not have header row. The columns in the CSV file must be in the same order as the columns in the table in storage. Use the 'columns' option to specify the column order.
    + ignoredLinesCount (optional, number) - Number of lines to skip at the beginning of the file. If ignoredLinesCount is specified, the withoutHeaders option will be ignored.
    + treatValuesAsNull (optional, array[string]) - (Snowflake and BigQuery only) Array of string values that should be imported as NULL values. The default value is `['']`. Some other common values you might consider are `'\N'` or `'null'`. **Currently only single value is allowed**, but it still must be sent as array to allow future expansion.
    + useTimestampFromDataFile (optional, boolean) - (Snowflake only) If `useTimestampFromDataFile` is `true`, it is required for input csv file to contain `_timestamp` column with valid datetime values.

        Specific behavior of BigQuery:

        * If the `treatValuesAsNull` parameter is empty array in the request, no values will be converted to NULL. Internally, the value `_\_KEBOOLA_IMPORT_AS_NULL_\_+UUID` will be used, e.g. `_\_KEBOOLA_IMPORT_AS_NULL_\_4b340550242239.64159797`. Such a value is highly unlikely to be present in the data, so no value will be converted to NULL.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "dataFileId": 12345,
                "incremental": false,
                "delimiter": ",",
                "enclosure": "\""
            }

+ Response 202 (application/json)

            {
                "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": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Import data from workspace asynchronously [POST]

The actual data must be provided in the following attributes:
- **dataWorkspaceId** and **dataObject** (older "dataTableName" is deprecated)

Import from table and file workspace is supported.

- For **table workspace** use `dataWorkspaceId` and set `dataObject` with name of source table.
- For **file workspace** use `dataWorkspaceId` and `dataObject` can be:
  - single file `file.csv`
  - folder `folder/` (mind the trailing slash)
  - manifest `file.csvmanifest`
- For **file workspace** always use `columns[]` attribute with list of imported columns.

Further information can be found in the [Developers Documentation](https://developers.keboola.com/integrate/storage/api/import-export/).

+ Parameters
    + table_id (required) - Target table ID

+ Attributes
    + dataWorkspaceId (required, number) - Load from the table [workspace](#reference/workspaces). Use with the **dataObject** attribute.
    + dataTableName (optional, string) - **Deprecated** (use dataObject instead) ~~Load from the table in the [workspace](#reference/workspaces).~~
    + dataObject (optional, string) - Load from the table/file in the [workspace](#reference/workspaces).
    + incremental (optional, boolean) - If `incremental` is a non-zero value, the import adds data to the existing data in the table. If `incremental` is `false`, the target table will be truncated before the import.
    + delimiter (optional, string) - Field delimiter used in the CSV file. The default value is `,`.  Use '\t' or type the tab char for tabulator.
    + enclosure (optional, string) - Field enclosure used in the CSV file. The default value is `"`. (Note: you can specify either `enclosure` or `escapedBy` parameter, not both.)
    + escapedBy (optional, string) - Escape character used in the CSV file. The default value is an empty value - no escape character is used. (Note: you can specify either `enclosure` or `escapedBy` parameter, not both.)
    + columns[] (optional, string) - List of columns present in the CSV file; the first line of the file will not be treated as a header!
    + withoutHeaders (optional, boolean) - The CSV file doesn't contain headers, columns are matched by their order. If this option is used, columns option is ignored.
    + deduplicationStrategy (optional, enum[string]) - (Snowflake only) Specifies how to handle duplicate rows in the imported data.
        + Members
            + upsert - Existing rows are updated with the new data, and new rows are added.
            + insert - New rows are added, and existing rows are not updated.
        + Default: upsert

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "dataWorkspaceId": 12345,
                "dataObject": "myTable",
                "incremental": false
            }

+ Response 202 (application/json)

            {
                "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": [],
                    },
                    "source": {
                        "workspaceId": "12345",
                        "dataObject": "myTable",
                        "tableName": "myTable",
                        "type": "file"
                    },
                    "queue": "main_fast"
                },
                "createdTime": "2017-02-13T12:51:48+0100",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

## Data Preview [/v2/storage/tables/{table_id}/data-preview/]
### Data preview [GET]

Returns up to 1000 rows from table in CSV (RFC) format. Rows can be filtered by various filters described below.
For full table download please read more in [Asynchronous Unload documentation](#reference/tables/unload-data-asynchronously).
For the description of filters, see [Asynchronous Unload documentation](#reference/tables/unload-data-asynchronously).

The `isTruncated` flag is `true` if the value is >16k chars and response type is JSON .


#### HTTP Compression

To enable compression of API response traffic, please include the following HTTP header with the API request: `Accept-encoding: gzip`.


+ Parameters
    + table_id (required) - Table Id

+ Attributes
    + limit (optional, number) - Limit the number of returned rows. Maximum allowed value is `1000`
        + Default: 100
    + changedSince (optional) - Filtering by import date - timestamp of import is stored within each row. Both until and since values can be a unix timestamp or any date accepted by [strtotime](http://www.php.net/manual/en/function.strtotime.php).
    + changedUntil (optional) - Filtering by import date - timestamp of import is stored within each row. Both until and since values 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`
    + columns (optional) - Comma separated list of columns to export; by default all columns are exported.
    + whereColumn (optional) - **Deprecated** (use whereFilters instead). Column for exporting only matching rows; see more in the rows filtering section.
    + whereValues[] (optional, array) - **Deprecated** (use whereFilters instead). Values for exporting only matching rows; see more in the rows filtering section.
    + whereOperator (optional, enum[string]) - **Deprecated** (use whereFilters instead). Operator for value comparison.
        + Members
            + eq - Equals - can be used with multiple values.
            + ne - Not equals - can be used with multiple values.
        + Default: eq
    + format (optional, enum[string]) - output format of preview
        + Members
            + rfc - will return CSV formatted output
            + json - will return JSON formatted output
        + Default: rfc
    + whereFilters (optional, array[WhereFiltersObject])
    + orderBy (optional, array[OrderByObject])
    + fulltextSearch (optional, string) - Makes fulltext search over all data in table. It cannot be combined with `whereFilters`. Snowflake/BigQuery only

+ Request with default `rfc` format (`CSV` data)

    + Headers

            X-StorageApi-Token: your_token
            Accept-encoding: gzip

+ Response 200 (text/csv)
    + Headers

            Content-Encoding: gzip

    + Body

            "id","name"
            "26","czech"
            "1","english"
            "11","finnish"
            "24","french"


+ Request with `&format=json`

    + Headers

            X-StorageApi-Token: your_token
            Accept-encoding: gzip

+ Response 200 (application/json)

        {
            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
                }
               ],
            ]
        }

## Unload Data Asynchronously [/v2/storage/tables/{table_id}/export-async]

### Asynchronous Export [POST]
Exports data into File Storage. The Id of the created file is returned.
This task is asynchronous; Id of the created file is stored in the `results` of the created job when the job is finished.

#### Rows filtering
Exported rows can be filtered by a single filter. Examples of filtering by `userId` column:

- Single value filter is used on one column. Equals to `UserId = 123`.
    ```
    {
        "whereFilters": [
            {
                "column": "UserID",
                "values": [
                    "123"
                ]
            }
        ]
    }
    ```
- Multiple value filter is used on one column. Equals to `UserId IN (123,234)`.
    ```
    {
        "whereFilters": [
            {
                "column": "UserID",
                "values": [
                    "123",
                    "234"
                ]
            }
        ]
    }
    ```
- Uses a non equals operator. Equals to `UserId != 123`.
    ```
    {
        "whereFilters": [
            {
                "column": "UserID",
                "values": [
                    "123"
                ],
                "operator": "ne"
            }
        ]
    }
    ```
- Uses greater than operator and cast value as double. Equals to `try_to_double(Price) > 40.3`.
    ```
    {
        "whereFilters": [
            {
                "column": "Price",
                "values": [
                    "40.3"
                ],
                "operator": "gt",
                "dataType": "DOUBLE"
            }
        ]
    }
    ```
- Uses TIME_STRING type to filter by date/time values. Values are converted to timestamps. Equals to filtering by timestamp column.
    ```
    {
        "whereFilters": [
            {
                "column": "created_at",
                "values": [
                    "2023-01-01 00:00:00",
                ],
                "operator": "ge",
                "type": "TIME_STRING"
            }
        ]
    }
    {
        "whereFilters": [
            {
                "column": "created_at",
                "values": [
                    "1672531200"
                ],
                "operator": "ge",
                "type": "TIME_STRING"
            }
        ]
    }
    {
        "whereFilters": [
            {
                "column": "created_at",
                "values": [
                    "-2 days"
                ],
                "operator": "ge",
                "type": "TIME_STRING"
            }
        ]
    }
    ```
 - For multiple filters use multiple objects. All filters are joined by AND expression.
    ```
    {
        "whereFilters": [
            {...},
            {...},
            {...}
        ]
    }
    ```

#### Rows sorting
Exported rows can be sorted by multiple columns. Examples of sorting:

- Sorting ascending by column UserId. Equals to `ORDER BY UserId ASC`.
    ```
    {
        "orderBy": [
            {
                "column": "UserId"
            }
        ]
    }
    ```
- Sorting descending by column UserId. Equals to `ORDER BY UserId DESC`.
    ```
    {
        "orderBy": [
            {
                "column": "UserId",
                "order": "DESC"
            }
        ]
    }
    ```
- Sorting descending by column Price with casting column Price to DOUBLE. Equals to `ORDER BY try_to_double(Price) DESC`.
    ```
    {
        "orderBy": [
            {
                "column": "Price",
                "order": "DESC",
                "dataType": "DOUBLE"
            }
        ]
    }
    ```

- For multiple sort condititions use multiple objects.
    ```
    {
        "orderBy": [
            {...},
            {...},
            {...}
        ]
    }
    ```

The comparison operator essentially behaves like the [SQL IN](http://www.w3schools.com/sql/sql_in.asp) (and NOT IN) operator. That is, the
`eq` value matches if any `whereValues` match, and the `new` value matches if none `whereValues` match.

#### Caching
Asynchronous exports support internal caching. When the export file for a certain table
export parameters was created and there were no changes in the table data since, the
previous cached file will be returned.

#### Job results

The response contains a link to job results. Once the job is finished, the job result
will show information about the created file and caching:

```
{
    "file": {
        "id": 234
    },
    "cacheHit": false
}
```

+ Parameters
    + table_id (required) - Table Id

+ Attributes
    + limit (optional, number) - Limit the number of returned rows.
    + sourceBranchId (optional) - Branch ID where to load the `source` from. If not provided, default branch will be used. Applicable when loading from `source` only.
    + days (optional, number) - **Deprecated** (use changedSince instead). ~~It returns rows created or updated in the last X days.~~
    + format (optional, enum[string]) - File format
        + Members
            + rfc - According to [RFC](http://www.ietf.org/rfc/rfc4180.txt).
            + json
        + Default: rfc
    + changedSince (optional) - Filtering by import date - timestamp of import is stored within each row. Both until and since values can be a unix timestamp.
    + changedUntil (optional) - Filtering by import date - timestamp of import is stored within each row. Both until and since values can be a unix timestamp.
    + columns (optional) - Comma separated list of columns to export; by default all columns are exported.
    + whereColumn (optional) - **Deprecated** (use whereFilters instead). ~~Column for exporting only matching rows; see more in the rows filtering section.~~
    + whereValues[] (optional) - **Deprecated** (use whereFilters instead). ~~Values for exporting only matching rows; see more in the rows filtering section.~~
    + whereOperator (optional, enum[string]) - **Deprecated** (use whereFilters instead). ~~Operator for value comparison.~~
        + Members
            + eq - Equals - can be used with multiple values.
            + ne - Not equals - can be used with multiple values.
        + Default: eq
    + whereFilters (optional, array[WhereFiltersObject])
    + orderBy (optional, array[OrderByObject])
    + gzip (optional, boolean) - The response will be gzipped if set to true.
    + includeInternalTimestamp (optional, boolean) - Include internal _timestamp column in the exported data (column is included even when not in columns list). This is timestamp of row last change. (Available only for Snowflake)
    + fileType (optional, enum[string]) - Type of the file to be created in File Storage.
        + Members
            + csv - CSV file
            + parquet - Parquet file
        + Default: csv
    + timezone (optional, string) - IANA timezone name (e.g. `America/Los_Angeles`, `Europe/Prague`). When set, Snowflake session timezone is configured before export, affecting TIMESTAMP_LTZ column display. Not supported for Parquet exports. Available only for Snowflake backend.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token
            Accept-encoding: gzip

+ Response 202 (application/json)

    + Body

            {
                "id": 22070936,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/22070936",
                "tableId": "in.c-main.test",
                "operationName": "tableExport",
                "operationParams": {
                    "export": {
                        "tableName": null,
                        "columns": [],
                        "limit": null,
                        "changedSince": null,
                        "changedUntil": null,
                        "gzipOutput": false,
                        "format": "rfc",
                        "whereFilters": [],
                        "fileType": "csv",
                        "timezone": null
                    },
                    "queue": "main_fast"
                },
                "createdTime": "2017-02-13T12:56:57+0100",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }


## Manage Tables [/v2/storage/tables/{table_id}]

### Table detail [GET]
Obtains information about a table.

- Definition property is available only for tables with [native datatypes](https://help.keboola.com/storage/tables/data-types/#native-datatypes).
- Data types in the definition are never alias/synonymous/virtual they are always base types. E.g. INT = NUMERIC(38,0) for Snowflake
- Configuration property is available only for tables with with configurations.

+ Parameters
    + table_id (required) - Table Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

            {
                "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": [],
                "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,
                "timestampType": "MANAGED",
                "tableType": "table",
                "path": "kbc_578.c-application-testing.cashier-data-alias",
                "definition": {
                    "primaryKeysNames": [],
                    "columns": [
                        {
                            "name": "visit_id",
                            "definition": {
                                "type": "VARCHAR",
                                "nullable": false,
                                "length": 16777216
                            },
                            "basetype": "STRING",
                            "canBeFiltered": true,
                        }
                    ],
                    "distribution": {
                        "type": "ROUND_ROBIN",
                        "distributionColumnsNames": ["visit_id"]
                    },
                    "index": {
                        "type": "CLUSTERED INDEX",
                        "indexColumnsNames": ["visit_id"]
                    },
                    "timePartitioning": {
                        "type": "DAY",
                        "expirationMs": 7776000000,
                        "field": "visit_id"
                    },
                    "rangePartitioning": {
                        "field": "visit_id",
                        "range": {
                            "start": 0,
                            "end": 1000000,
                            "interval": 1000
                        }
                    },
                    "clustering": {
                        "fields" : ["visit_id"]
                    },
                    "requirePartitionFilter": false,
                    "partitions": {
                        "partitionId": "1234",
                        "rowsNumber": "10",
                        "lastModifiedTime": "2022-12-13 00:09:25.604000 UTC",
                        "storageTier": "ACTIVE"
                    }
                },
                "sourceTable": {
                    "id": "in.c-application-testing.cashier-data",
                    "uri": "https://connection.keboola.com/v2/storage/tables/in.c-application-testing.cashier-data",
                    "isAlias": false,
                    "project": {
                        "id": 123,
                        "name": "Some source project"
                    },
                    "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,
                            }
                        ],
                        "distribution": {
                            "type": "ROUND_ROBIN",
                            "distributionColumnsNames": ["visit_id"]
                        },
                        "index": {
                            "type": "CLUSTERED INDEX",
                            "indexColumnsNames": ["visit_id"]
                        },
                        "timePartitioning": {
                            "type": "DAY",
                            "expirationMs": 7776000000,
                            "field": "visit_id"
                        },
                        "rangePartitioning": {
                            "field": "visit_id",
                            "range": {
                                "start": 0,
                                "end": 1000000,
                                "interval": 1000
                            }
                        },
                        "clustering": {
                            "fields" : ["visit_id"]
                        },
                        "requirePartitionFilter": false,
                        "partitions": {
                            "partitionId": "1234",
                            "rowsNumber": "10",
                            "lastModifiedTime": "2022-12-13 00:09:25.604000 UTC",
                            "storageTier": "ACTIVE"
                        }
                    }
                },
                "aliasColumnsAutoSync": true,
                "columns": [
                    "time_spent_in_shop",
                    "number_of_items",
                    "customer_shoe_size",
                    "customer_age",
                    "age_segment",
                    "no_segment",
                    "customer_segment",
                    "visit_id"
                ],
                "columnMetadata": [],
                "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/tables",
                    "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,
                    "metadata": [],
                    "backendPath": [
                        "KBC_PRJ_123",
                        "in.c-main"
                    ],
                },
                "configuration": {
                    "componentId": "keboola.app-custom-query-manager",
                    "branchId": 1,
                    "configurationId": "my-configuration",
                    "migrationIndex":0,
                }
            }

### Table update [PUT /v2/storage/tables/{table_id}/?async={async}]
Update an existing table

+ Parameters
    + table_id (required) - Table Id
    + async (optional, boolean) - Updates the table in a background job. This is useful if updates takes too much time and times out.

+ Attributes
    + displayName (required, string) - Table displayName, this name is displayed in UI and can be changed anytime; only alphanumeric characters,underscores and dashes are allowed.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "displayName": "updated-table-display-name"
            }

+ Response 200 (application/json)
Synchronous call response (async=false)
    + Body

            {
                "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": "my-display-name",
                "transactional": false,
                "primaryKey": [],
                "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,
                "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",
                    "isAlias": false,
                    "project": {
                        "id": 123,
                        "name": "Some source project"
                    },
                    "columnMetadata": {
                        "number_of_items": [
                            {
                                "id": "207947778",
                                "key": "KBC.datatype.basetype",
                                "value": "INTEGER",
                                "provider": "user",
                                "timestamp": "2019-08-14T16:55:34+0200"
                            }
                        ]
                    }
                },
                "aliasColumnsAutoSync": true,
                "columns": [
                    "time_spent_in_shop",
                    "number_of_items",
                    "customer_shoe_size",
                    "customer_age",
                    "age_segment",
                    "no_segment",
                    "customer_segment",
                    "visit_id"
                ],
                "columnMetadata": [],
                "metadata": [],
                "bucket": {
                    "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-application-testing",
                    "id": "in.c-application-testing",
                    "name": "c-application-testing",
                    "stage": "in",
                    "description": "",
                    "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-application-testing/tables",
                    "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,
                    "metadata": [],
                    "backendPath": [
                        "KBC_PRJ_123",
                        "in.c-main"
                    ],
                },
                 "configuration": {
                     "componentId": "keboola.app-custom-query-manager",
                     "branchId": 1,
                     "configurationId": "my-configuration",
                     "migrationIndex":0,
                 }
            }
+ Response 202 (application/json)
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "tableUpdate",
                "operationParams": {
                    "values": {
                        "displayName": "updated-table-display-name"
                    },
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "roman.bracinik@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Drop table [DELETE /v2/storage/tables/{table_id}?force={force}&async={async}]
Deletes a table from Storage. In default mode, only table having any aliases can be deleted.
Use the optional `force` parameter to delete its aliases too.

+ Parameters
    + table_id (required) - Table Id
    + force (optional, boolean) - Drops the table and its aliases.
    + async (optional, boolean) - Execute drop table in asynchronous job. Sync operation is deprecated.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204
+ Response 202 (application/json)
    + Body

            {
               "id":1189,
               "status":"waiting",
               "url":"https:\/\/connection.keboola.com\/v2\/storage\/jobs\/1189",
               "tableId":"in.c-main.another",
               "operationName":"tableDrop",
               "operationParams":{
                  "force":"true"
               },
               "createdTime":"2013-07-08T10:01:03+0200",
               "startTime":null,
               "endTime":null,
               "runId":null,
               "results":null,
               "creatorToken":{
                  "id":"221",
                  "name":"Master Token"
               }
            }




## List Tables [/v2/storage/tables?include={include}]

### List All Tables [GET]
Lists all tables accessible by the token. By default, all tables are returned with their
attributes and information about the containing bucket.

+ Parameters
    + include (optional, enum[string]) - Comma separated list of resources to include for each table.
        + Members
            + buckets
            + bucketsWithoutSourceTables
            + 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. Works across projects for linked buckets
        + Default: metadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "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",
                    "columns": [
                        "time_spent_in_shop",
                        "number_of_items",
                        "customer_shoe_size",
                        "customer_age",
                        "age_segment",
                        "no_segment",
                        "customer_segment",
                        "visit_id"
                    ],
                    "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",
                        "tables": "https:\/\/connection.keboola.com\/v2\/storage\/buckets\/in.c-application-testing\/tables",
                        "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,
                    },
                    "columnMetadata": {
                        "number_of_items": [
                            {
                                "id": "207947778",
                                "key": "KBC.datatype.basetype",
                                "value": "INTEGER",
                                "provider": "user",
                                "timestamp": "2019-08-14T16:55:34+0200"
                            }
                        ]
                    }
                },
                {
                    "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": [],
                    "created": "2016-06-23T20:41:38+0200",
                    "lastImportDate": "2016-07-07T11:26:03+0200",
                    "lastChangeDate": "2016-07-07T11:26:05+0200",
                    "rowsCount": 48,
                    "dataSizeBytes": 12288,
                    "isAlias": true,
                    "isAliasable": true,
                    "isTyped": 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",
                        "isAlias": false,
                        "project": {
                            "id": 578,
                            "name": "Some source project"
                        },
                        "columnMetadata": {
                            "number_of_items": [
                                {
                                    "id": "207947778",
                                    "key": "KBC.datatype.basetype",
                                    "value": "INTEGER",
                                    "provider": "user",
                                    "timestamp": "2019-08-14T16:55:34+0200"
                                }
                            ]
                        }
                    },
                    "aliasColumnsAutoSync": true,
                    "columns": [
                        "time_spent_in_shop",
                        "number_of_items",
                        "customer_shoe_size",
                        "customer_age",
                        "age_segment",
                        "no_segment",
                        "customer_segment",
                        "visit_id"
                    ],
                    "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",
                        "tables": "https:\/\/connection.keboola.com\/v2\/storage\/buckets\/in.c-application-testing\/tables",
                        "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,
                    },
                    "columnMetadata": []
                }
            ]


## Create Table Column [/v2/storage/tables/{table_id}/columns/]

### Add Column to Table [POST]
Adds a new column to an existing table. This request is [asynchronous](#introduction/synchronous-and-asynchronous-calls).

*Attribute definition and basetype is allowed (and required) for typed tables created via [table definition](#reference/tables/create-table-definition)*.

+ Parameters
    + table_id (required) - Table Id

+ Attributes
    + name (required, string) - column name
    + definition (optional, object) - column settings, this object is applicable when table is typed. Otherwise it is ignored
        + type (required, string) - datatype of this column, choose build in types for used backend [Snowflake](https://bit.ly/3A5CkT8), [BigQuery](https://bit.ly/3jcQ8VX)
        + length (string) - optional, default: depends on type
        + nullable (boolean) - optional, default: true; BigQuery: BQ doesn't support adding a REQUIRED column to an existing table schema so if this parameter is present, it has to be true.
        + default (string) - optional, default value for column, not supported by BigQuery
    + basetype (optional, enum[string]) - base datatype of this column, will be converted to backend specific types
        + Members
            + BOOLEAN
            + DATE
            + FLOAT
            + INTEGER
            + NUMERIC
            + STRING
            + TIMESTAMP

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "new-column"
            }

+ Response 202 (application/json)
    + Body

            {
               "id":1189,
               "status":"waiting",
               "url":"https:\/\/connection.keboola.com\/v2\/storage\/jobs\/1189",
               "tableId":"in.c-main.another",
               "operationName":"tableColumnAdd",
               "operationParams":{
                  "name":"new-column"
               },
               "createdTime":"2013-07-08T10:01:03+0200",
               "startTime":null,
               "endTime":null,
               "runId":null,
               "results":null,
               "creatorToken":{
                  "id":"221",
                  "name":"Master Token"
               }
            }

## Manage Table Columns [/v2/storage/tables/{table_id}/columns/{column_name}]

### Delete Column from Table [DELETE /v2/storage/tables/{table_id}/columns/{column_name}/?force={force}]
Deletes an existing column from an existing table. This request is [asynchronous](#introduction/synchronous-and-asynchronous-calls).
Use the optional `force` parameter to delete the column from table aliases too.

+ Parameters
    + table_id (required) - Table Id
    + column_name (required) - Column Name
    + force (optional, boolean) - Delete the column from table and table aliases. All aliases must have `aliasColumnsAutosync` enabled.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202 (application/json)
    + Body

            {
               "id":1189,
               "status":"waiting",
               "url":"https:\/\/connection.keboola.com\/v2\/storage\/jobs\/1189",
               "tableId":"in.c-main.another",
               "operationName":"tableColumnDelete",
               "operationParams":{
                  "name":"new-column",
                  "force": false
               },
               "createdTime":"2013-07-08T10:01:03+0200",
               "startTime":null,
               "endTime":null,
               "runId":null,
               "results":null,
               "creatorToken":{
                  "id":"221",
                  "name":"Master Token"
               }
            }

## Primary Keys [/v2/storage/tables/{table_id}/primary-key/]
### Create Primary Key [POST]
If a primary key is set, updates can be done on the table. A primary key can be composed of multiple columns.
This request is [asynchronous](#introduction/synchronous-and-asynchronous-calls).

+ Parameters
    + table_id (required) - Table Id

+ Attributes
    + columns[] (required) - Array of columns used as the primary key
    + skipDuplicatesCheck (optional, boolean) - If set to true, the duplicity check will be skipped when creating the primary key. This allows creating a primary key on a table with duplicate values in the key columns. Only supported for Snowflake backend. Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "columns": [
                    "id"
                ],
                "skipDuplicatesCheck": false
            }

+ Response 202 (application/json)
    + Body

            {
               "id":1189,
               "status":"waiting",
               "url":"https:\/\/connection.keboola.com\/v2\/storage\/jobs\/1189",
               "tableId":"in.c-main.another",
               "operationName":"tablePrimaryKeyAdd",
               "operationParams":{
                  "columns":["id"],
                  "skipDuplicatesCheck":false
               },
               "createdTime":"2013-07-08T10:01:03+0200",
               "startTime":null,
               "endTime":null,
               "runId":null,
               "results":null,
               "creatorToken":{
                  "id":"221",
                  "name":"Master Token"
               }
            }

### Remove Primary Key [DELETE]
Removes the primary key from a table. This request is [asynchronous](#introduction/synchronous-and-asynchronous-calls).

+ Parameters
    + table_id (required) - Table Id

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202 (application/json)
    + Body

            {
               "id":1189,
               "status":"waiting",
               "url":"https:\/\/connection.keboola.com\/v2\/storage\/jobs\/1189",
               "tableId":"in.c-main.another",
               "operationName":"tablePrimaryKeyDelete",
               "operationParams":{
               },
               "createdTime":"2013-07-08T10:01:03+0200",
               "startTime":null,
               "endTime":null,
               "runId":null,
               "results":null,
               "creatorToken":{
                  "id":"221",
                  "name":"Master Token"
               }
            }


## Manage Table Rows [/v2/storage/tables/{table_id}/rows]

### Delete Table Rows [DELETE]
Deletes all rows matching the specified filter. The number of deleted rows is returned.
This request is [asynchronous](#introduction/synchronous-and-asynchronous-calls).

+ Parameters
    + table_id (required) - Table Id

+ Attributes
    + changedSince - (optional) filtering by import date - timestamp of import is stored within each row. Both until and since values 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`
    + changedUntil - (optional) filtering by import date - timestamp of import is stored within each row. Both until and since values 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`
    + whereColumn (optional) - **Deprecated** (use whereFilters instead). ~~Column for exporting only matching rows, see more in the [rows filtering section](#reference/tables/unload-data-asynchronously/asynchronous-export).~~
    + whereValues[] (optional) - **Deprecated** (use whereFilters instead). ~~Values for exporting only matching rows, see more in the [rows filtering section](#reference/tables/unload-data-asynchronously/asynchronous-export).~~
    + whereOperator (optional, enum[string]) - **Deprecated** (use whereFilters instead). ~~Operator for value comparison.~~
        + Members
            + eq - Equals - can be used with multiple values.
            + ne - Not equals - can be used with multiple values.
        + Default: eq
    + whereFilters[] (optional)
        + column (required) - column which should be matched
        + operator (optional, enum[string]) - operator for value comparison
            + Members
                + eq - Equals - can be used with multiple values
                + ne - Not equals  - case be used with multiple values
            + Default: eq
        + values[] (required, array) - array of variables to compare
        + valuesByTableInWorkspace (optional) - Available with project feature `delete-rows-by-reference`. Exclusive with `values` (just one param possible). Snowflake|BigQuery only.
            + workspaceId (number) - ID of workspace (returned by Storage API)
            + table (string) - Exact name of table present in the workspace when doing this API call
            + column (string) - Name of the column, which values (all rows) will be used as values to DELETE rows by. Datatype of this column has to match with datatype of the column specified in root of this API call.

        + dataType (optional, enum[string]) - For comparing (`[gt|lt|le|ge]`) numeric values you have to specify data type. BigQuery supports all listed types and converts them to BigQuery equivalent in the background
            + Members
                + INTEGER - for numbers without a decimal point (Snowflake, BigQuery)
                + DOUBLE - for number with a decimal point (Snowflake, BigQuery)
                + BIGINT - for number without a decimal point (BigQuery)
                + REAL - for number with a decimal point (BigQuery)
                + DECIMAL - for numbers (BigQuery)
        + type (optional, enum[string]) - type of filter values interpretation
            + Members
                + SCALAR - default value type interpretation (default)
                + TIME_STRING - values are interpreted as date/time strings and converted to timestamps. When using TIME_STRING, dataType must be empty. Values must be valid date/time strings compatible with strtotime() or unix timestamps. All time strings are converted to UTC timezone. Be aware of your backend timezone settings and daylight saving time changes.
            + Default: SCALAR
    + allowTruncate - (optional, boolean) is used to confirm that you really want to delete all rows in case you did not specify any filters.
        + default: false

+ Request using whereFilters, send as form-data (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "whereFilters": [
                    {
                        "column": "id",
                        "operator": "eq",
                        "values": [
                            "12344"
                        ]
                    }
                ]
            }

+ Request using deprecated attributes, send as form-data (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "whereColumn": "id",
                "whereOperator": "eq",
                "whereValues": [
                    "12344"
                ]
            }

+ Response 202 (application/json)
    + Body

            {
               "id":1190,
               "status":"waiting",
               "url":"https:\/\/connection.keboola.com\/v2\/storage\/jobs\/1190",
               "tableId":"in.c-main.another",
               "operationName":"tableRowsDelete",
               "operationParams":{
                  "request": {
                      "changedUntil": null,
                      "changedSince": null,
                      "whereFilters": [
                          {
                              "column": "id,
                              "values": ["12344"],
                              "operator": "eq"
                          }
                      ]
                  }
               },
               "createdTime":"2013-07-08T10:01:03+0200",
               "startTime":null,
               "endTime":null,
               "runId":null,
               "results":null,
               "creatorToken":{
                  "id":"221",
                  "name":"Master Token"
               }
            }

## Data profiling [/v2/storage/tables/{table_id}/profile]

### Create profile [POST]
Create new data profile of table and its columns. Still under development. Available for BigQuery and Snowflake backends.
This request is [asynchronous](#introduction/synchronous-and-asynchronous-calls).

+ Parameters
    + table_id (required) - Table Id

+ Request
    + Headers
        X-StorageApi-Token: your_token

+ Response 202 (application/json)
    + Body

            {
               "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",
                  "name":"Master Token"
               }
            }

### Get profile [GET /v2/storage/tables/{table_id}/profile/latest]
Returns latest data profile of table and its columns.

+ Parameters
    + table_id (required) - Table Id

+ Request
    + Headers

        X-StorageApi-Token: your_token

+ Response 202 (application/json)
    + Body

        {
            "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
                    }
                }
            ]
        }


# Group Table Aliases
[Aliases](https://help.keboola.com/storage/tables/) behave like database Views. Alias tables are read-only.
Aliases cannot be chained and can be applied only between buckets with the same backend.

Rows present in an alias table can be filtered by a simple condition similar to
[table export filtering](#reference/tables/unload-data-asynchronously/asynchronous-export).
The filter parameter `aliasFilter` must be set during an alias table creation or later to enable filtering:

* **column** - Filtered by column name
* **operator** - Filter operator: `eq`, `ne`
* **values[]** - One or more filter values

#### Alias table columns
By default, the alias columns are automatically synced with the source table. You can disable this behaviour
by setting up `aliasColumnsAutosync` to `false` and setting up list of columns by `aliasColumns` parameter.
Later you can modify the alias columns by the table columns methods.
When turning `aliasColumnsAutoSync` back on, the columns will be immediately synced with the source table.

## Create Table Alias [/v2/storage/buckets/{bucket_id}/table-aliases]

### Create new alias table [POST]

An alias cannot be created from tables in an external bucket or from a table in a development branch. Additionally, an alias cannot be created in an external bucket itself.

+ Parameters
    + bucket_id (required) - Id of a bucket in which the alias table will be created.

+ Attributes
    + sourceTable (required) - Id of the source table
    + name (optional) - Name of the new table alias; If not set, will use source table name.
    + aliasColumns[] (optional) - List of alias columns; this disables column synchronization with the source table.
    + aliasColumnsAutosync (optional, boolean) - **Deprecated** (It is set automatically depends on `aliasColumns` is filled or not.) ~~Disables column synchronization with the source table.~~
        Default: false
    + aliasFilter[column] (optional) - Name of the column for filtering
    + aliasFilter[operator] (optional, enum[string]) - Comparison operator
        + Members
            + eq - Equal to
            + ne - Not equal to
        + Default: eq
    + aliasFilter[values][] (optional) - Values for the filter

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "sourceTable": "in.c-main.data",
                "name": "test-alias2",
                "aliasFilter": {
                    "column": "campaign_id",
                    "values": [
                        "68abf5473f",
                        "03e9b81530"
                    ],
                    "operator": "eq"
                },
                "aliasColumns": [
                    "campaign_id",
                    "email"
                ]
            }

+ Response 201 (application/json)
    + Body

            {
                "uri": "https://connection.keboola.com/v2/storage/tables/in.c-Test2.test-alias2",
                "id": "in.c-Test2.test-alias2",
                "name": "test-alias2",
                "displayName": "test-alias2-displayName",
                "transactional": false,
                "primaryKey": [],
                "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,
                "sourceTable": {
                    "id": "in.c-main.data",
                    "uri": "https://connection.keboola.com/v2/storage/tables/in.c-main.data",
                    "isAlias": false,
                    "project": {
                        "id": 578,
                        "name": "Odinuv Sandbox"
                    }
                },
                "aliasColumnsAutoSync": false,
                "aliasFilter": {
                    "column": "campaign_id",
                    "operator": "eq",
                    "values": [
                        "68abf5473f",
                        "03e9b81530"
                    ]
                },
                "columns": [
                    "campaign_id",
                    "email"
                ],
                "bucket": {
                    "uri": "https://connection.keboola.com/v2/storage/buckets/in.c-Test2",
                    "id": "in.c-Test2",
                    "name": "c-Test2",
                    "displayName": "Test2",
                    "stage": "in",
                    "description": "",
                    "tables": "https://connection.keboola.com/v2/storage/buckets/in.c-Test2/tables",
                    "created": "2017-02-13T11:41:55+0100",
                    "lastChangeDate": "2017-02-13T13:50:55+0100",
                    "isReadOnly": false,
                    "dataSizeBytes": 0,
                    "rowsCount": 0,
                    "isMaintenance": false,
                    "backend": "snowflake",
                    "sharing": null,
                    "backendPath": [
                        "KBC_PRJ_123",
                        "in.c-main"
                    ],
                }
            }

+ Response 202
Returned when the alias qualifies for BigQuery VIEW persistence (BigQuery non-linked bucket with BigQuery source table). Alias creation runs asynchronously via a storage job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "aliasCreate",
                "operationParams": {
                    "params": {
                    }
                }
            }


## Manage Alias Filters [/v2/storage/tables/{table_id}/alias-filter]

### Update Alias Filter [POST]
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.

+ Parameters
    + table_id (required) - Id of the alias table

+ Attributes
    + column (optional) - Column name
    + values[] (optional) - Column filter values
    + operator (optional, enum[string]) - Comparison operator
        + Members
            + eq - Equal to
            + ne - Not equal to
        + Default: eq

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "column": "campaign_id",
                "values": [
                    "68abf5473f"
                ]
            }

+ Response 200 (application/json)
    + Body

            {
                "uri": "https://connection.keboola.com/v2/storage/tables/in.c-Test2.test-alias2",
                "id": "in.c-Test2.test-alias2",
                "name": "test-alias2",
                "displayName": "test-alias2-displayName",
                "transactional": false,
                "primaryKey": [],
                "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,
                "sourceTable": {
                    "id": "in.c-main.data",
                    "uri": "https://connection.keboola.com/v2/storage/tables/in.c-main.data",
                    "isAlias": false,
                    "project": {
                        "id": 578,
                        "name": "Odinuv Sandbox"
                    }
                },
                "aliasColumnsAutoSync": false,
                "aliasFilter": {
                    "column": "campaign_id",
                    "operator": "eq",
                    "values": [
                        "68abf5473f"
                    ]
                }
            }

### Remove Alias Filter [DELETE]
Deletes a filter from an alias. The alias table will contain all rows from the source table.

+ Parameters
    + table_id (required) - Id of the alias table

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204


## Alias Column Synchronization [/v2/storage/tables/{table_id}/alias-columns-auto-sync]

### Enable Column Synchronization [POST]
Enables automatic column synchronization between the alias and source table. All columns from the source table
will be immediately synchronized into the alias table.

+ Parameters
    + table_id (required) - Id of the alias table

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204


### Disable Column Synchronization [DELETE]
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. When you add new columns into the source table, they
will not propagate to the alias.

+ Parameters
    + table_id (required) - Id of the alias table

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204


# Group Table Snapshotting
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.

## Create or List Snapshots [/v2/storage/tables/{table_id}/snapshots]

### Create Table Snapshot [POST]
**Snapshot creation is not supported for tables in external buckets.**

Creates a snapshot of the current state of the table. This request is [asynchronous](#introduction/synchronous-and-asynchronous-calls).
A table snapshot will contain:
- Table data,
- Table properties (primary key, etc.),

Snapshots of an alias table contain only alias settings, actual data are not stored with the snapshot.

+ Parameters
    + table_id (required) - Id of a table

+ Attributes
    + description (optional) - Snapshot description

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "description": "My first snapshot"
            }

+ Response 202 (application/json)
    + Body

            {
                "id": 22073730,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/22073730",
                "tableId": "in.c-main.test",
                "operationName": "tableSnapshotCreate",
                "operationParams": {
                    "description": null,
                    "queue": "main_fast"
                },
                "createdTime": "2017-02-13T14:44:46+0100",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }


### List Table Snapshots [GET /v2/storage/tables/{table_id}/snapshots?limit={limit}&offset={offset}]
Retrieves a list of all snapshots of a table.

+ Parameters
    + table_id (required) - Id of a table
    + limit (number, optional) - Pagination limit
        + Default: 20
    + offset (number, optional) - Pagination offset
        + Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200
    + Headers

            Content-type: application/json

    + Body

            [
                {
                "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"
                },
                "uri": "https://connection.keboola.com/v2/storage/snapshots/82629",
                "dataFileId": "188803533"
                }
            ]

## Manage Snapshots [/v2/storage/snapshots/{snapshot_id}]

### Snapshot Detail [GET]
Retrieves information about a single table snapshot.

+ Parameters
    + snapshot_id - Id of the snapshot; use the
    [List Snapshots Call](#reference/table-snapshotting/create-or-list-snapshots/list-table-snapshots) to find snapshot Id.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "id": "20",
                "description": "",
                "createdTime": "2013-08-12T12:33:04+0200",
                "type": "table",
                "creatorToken": {
                    "id": 221,
                    "description": "Master Token"
                },
                "dataFileId": "161757",
                "table": {
                    "id": "in.c-dalsi.alias",
                    "primaryKey": [],
                    "columns": [
                        "id",
                        "name"
                    ]
                }
            }


### Delete Table Snapshot [DELETE]
Removes a table snapshot. The current table data is not modified. This request
is [asynchronous](#introduction/synchronous-and-asynchronous-calls).

+ Parameters
    + snapshot_id - Id of the snapshot. Use the
    [List Snapshots Call](#reference/table-snapshotting/create-or-list-snapshots/list-table-snapshots) to find snapshot Id.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 202 (application/json)
    + Body

            {
                "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",
                    "name":"Master Token"
                }
            }


# Group Workspaces
Workspaces provide a playground for your data. You can load data from your storage, explore or modify it
and then, optionally, load it back to storage tables. A workspace is represented by access credentials to a storage
backend with permissions to write to the workspace specific database schema.

All workspaces endpoints can be used with `default` for `branch_id` parameter and emulate call endpoint without development branch.
It means that endpoint `GET /v2/storage/workspaces` is the same as `GET /v2/storage/branch/default/workspaces`.

## Workspaces Collection [/v2/storage/workspaces]

### Create Workspace [POST /v2/storage/workspaces?async={async}]
Creates a new workspace and return its credentials.
NOTE: To create reader workspace, use Create Configuration Workspaces endpoint instead.

+ Parameters
    + async (optional, boolean) - Create workspace in a background job. Calling the parameter as `async=false` is deprecated.

+ Attributes
    + backend: snowflake (optional, enum[string]) - Workspace backend. When omitted, the default backend is used.
        + Members
            + snowflake
            + bigquery
            + abs - Azure blob storage file workspace
    + backendSize: small (optional, enum[string]) - Workspace backend size. Available only for `snowflake` backend and projects having `workspace-snowflake-dynamic-backend-size` feature enabled.
        + Members
            + small
            + medium
            + large
    + networkPolicy: system (optional, enum[string]) - Network policy applied to workspace user when created.
            + Members
                + system
                + user
    + readOnlyStorageAccess: (optional, boolean) - Allows read only access to all objects in Storage.
    + loginType: (optional, enum[string]) - Request credentials type for new workspace. backend attribute is required when loginType is set.
        + Members
            + default
            + `snowflake-legacy-service` - LEGACY_SERVICE type user is created with password
            + `snowflake-person-sso` - PERSON type user is created without password, login is possible only from Keboola Connection UI
            + `snowflake-person-keypair` - PERSON type user is created with keypair authentication (publicKey required)
            + `snowflake-service-keypair` - SERVICE type user is created with keypair authentication (publicKey required)
    + publicKey: (optional, string) - Public key for user authentication. Required when loginType is set to `snowflake-person-keypair`.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "backend": "snowflake"
            }

+ Response 201 (application/json)
Synchronous call response (async=false)
   + Attributes (WorkspaceCreated)

+ Response 202 (application/json)
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "workspaceCreate",
                "operationParams": {
                    "values": {
                        "backend": "snowflake"
                        "branchId": 1
                    },
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "roman.bracinik@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Create Development Branch Workspace [POST /v2/storage/branch/{branch_id}/workspaces?async={async}]
Creates a new workspace for [Development Branch](#reference/development-branches) and return its credentials.

+ Parameters
    + branch_id (required) - Id of the development branch
    + async (optional, boolean) - Create workspace in a background job.

+ Attributes
    + backend: snowflake (optional, enum[string]) - Workspace backend. When omitted, the default backend is used.
        + Members
            + snowflake
            + bigquery
            + abs - Azure blob storage file workspace
    + backendSize: small (optional, enum[string]) - Workspace backend size. Available only for `snowflake` backend and projects having `workspace-snowflake-dynamic-backend-size` feature enabled.
        + Members
            + small
            + medium
            + large
    + networkPolicy: system (optional, enum[string]) - Network policy applied to workspace user when created.
            + Members
                + system
                + user
    + readOnlyStorageAccess: (optional, boolean) - Allows read only access to all objects in Storage.
    + loginType: (optional, enum[string]) - Request credentials type for new workspace. backend attribute is required when loginType is set.
        + Members
            + default
            + `snowflake-legacy-service` - LEGACY_SERVICE type user is created with password
            + `snowflake-person-sso` - PERSON type user is created without password, login is possible only from Keboola Connection UI
            + `snowflake-person-keypair` - PERSON type user is created with keypair authentication (publicKey required)
            + `snowflake-service-keypair` - SERVICE type user is created with keypair authentication (publicKey required)
    + publicKey: (optional, string) - Public key for user authentication. Required when loginType is set to `snowflake-person-keypair`.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "backend": "snowflake"
            }

+ Response 201 (application/json)
Synchronous call response (async=false)
   + Attributes (WorkspaceCreated)

+ Response 202 (application/json)
Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "workspaceCreate",
                "operationParams": {
                    "values": {
                        "backend": "snowflake"
                        "branchId": 1
                    },
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "roman.bracinik@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }


### List Workspaces [GET]
Returns all workspaces for the project.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

   + Attributes (array[Workspace])

### List Development Branch Workspaces [GET /v2/storage/branch/{branch_id}/workspaces]
Returns all workspaces for the project in [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

   + Attributes (array[Workspace])

## Manage Workspace [/v2/storage/workspaces/{workspace_id}]

### Workspace Detail [GET]
Retrieves information about a given workspace. Note that the password to the workspace can be retrieved only when the workspace is created.

+ Parameters
    + workspace_id (number)

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

    + Attributes (Workspace)

### Development Branch Workspace Detail [GET /v2/storage/branch/{branch_id}/workspaces/{workspace_id}]
Retrieves information about a given workspace in [Development Branch](#reference/development-branches). Note that the password to the workspace can be retrieved only when the workspace is created.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (number)

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

    + Attributes (Workspace)

### Delete Workspace [DELETE /v2/storage/workspaces/{workspace_id}/?async={async}]
Deletes a workspace. This also irreversibly removes the workspace content.

+ Parameters
    + workspace_id (required, number)
    + async (optional, boolean) - Workspace will be deleted [asynchronously](#introduction/synchronous-and-asynchronous-calls). A job will be created and enqueued.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

### Delete Development Branch Workspace [DELETE /v2/storage/branch/{branch_id}/workspaces/{workspace_id}/?async={async}]
Deletes a workspace in [Development Branch](#reference/development-branches). This also irreversibly removes the workspace content.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (required, number)
    + async (optional, boolean) - Workspace will be deleted [asynchronously](#introduction/synchronous-and-asynchronous-calls). A job will be created and enqueued.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

## Load Data [/v2/storage/workspaces/{workspace_id}/load]

### Load Data [POST]

Loads tables from Storage into a Workspace. BigQuery supports only loading as view.

+ Parameters
    + workspace_id (required, number)

+ Attributes
    + input[] (required, array) - Mappings of source tables with destinations to be loaded into the workspace
        + Items
            + (object)
                + Properties
                    + source (optional) - Required for loading table. Full table identifier of the source table (e.g.: in.c-bucket.mytable)
                    + sourceBranchId (optional) - Branch ID where to load the `source` from. If not provided, default branch will be used. Applicable when loading from `source` only.
                    + dataFileId (optional, number) - Required for loading file. File upload id. Can be used only to load file to file workspace.
                    + destination (required) - Destination table name or folder for file workspace
                    + rows (optional, number) - Limits the number of returned rows
                    + seconds (optional, number) - **Deprecated** (use changedSince and changedUntil instead). Returns rows created or updated in the last X seconds.
                    + changedSince (optional) - Currently only supported for Snowflake - Filtering by import date - timestamp of import is stored within each row. Both until and since values can be a unix timestamp.
                        **If the `days` or `seconds` parameter is set, this value is ignored.**
                    + changedUntil (optional) - Currently only supported for snowflake - Filtering by import date - timestamp of import is stored within each row. Both until and since values can be a unix timestamp.
                        **If the `days` or `seconds` parameter is set, this vallue are ignored.**
                    + columns[] (optional, array) - Array of column definition; by default all columns are exported.
                        + Items
                            + (object)
                                + Properties
                                    + source (required, string) - Column name
                                    + destination (optional, string) - Destination column name. If not set, source column name will be used.
                                    + type (optional, string) - Data type, eg. VARCHAR (ignored for tables with types)
                                    + length (optional, string) - Data type size, where applicable, eg. 255 for VARCHAR or 10,2 for NUMBER (ignored for tables with types)
                                    + nullable (optional, boolean) - Allow NULL values in destination table (ignored for tables with types)
                                        Default: true
                                    + convertEmptyValuesToNull (optional, boolean) - Empty values replaced by NULL (ignored for tables with types)
                                        Default: false

                    + whereColumn (optional) - **Deprecated** (use whereFilters instead). Column for [filtering](#reference/tables/unload-data-asynchronously/asynchronous-export)
                    + whereValues[] (optional) - **Deprecated** (use whereFilters instead). Values for filtering
                    + whereOperator (optional, enum[string]) - **Deprecated** (use whereFilters instead). Comparison operator
                        + Members
                            + eq - Equal to
                            + ne - Not equal to
                        + Default: eq
                    + whereFilters (optional, array[WhereFiltersObject])
                    + incremental (optional, boolean) - Rows will be appended to an existing table, not supported in file workspaces (load is always full)
                        Default: false
                    + overwrite (optional, boolean) - When preserve is true duplicate tables will be overwritten
                        Default: false
                    + loadType (optional, enum[string]) - Select load type. Default: COPY. Use AUTO to let Storage API decide the best load type. Copy will be used always when filters, columns, or incremental are set. Clone is supported on Snowflake and BigQuery backends and accepts only "source", "destination", "overwrite" and "dropTimestampColumn" options. Clone is not supported with incremental loading or for linked buckets on BigQuery. View load type is experimental for SNFLK requires feature `input-mapping-read-only-storage`, aliases are not supported, for BigQuery working without feature, aliases are not supported. View will be created in workspace instead of loading table (View accepts only "source","destination" and "overwrite" options).
                        + Members
                            + COPY
                            + CLONE
                            + VIEW
                            + AUTO
                    + primaryKey - optional definition of primaryKey on created Workspace table. When PK created with this definition, it will respect nullabiltiy defined in `columns` field, which is different from inheriting PK from Storage, because inherited PK is forced to be non-nullable. Snowflake only.
                        + authority (required, enum[string]) - also accepts legacy name `autority`
                            + Members
                                + storage - PK should be inherited from Storage
                                + manual - manual list of columns to set as PK
                            + Default: storage
                        + columns (optional, array) - list of columns to define private key on.
                    + dropTimestampColumn (optional, boolean) - (CLONE loadType only) When true _timestamp column is removed after table load
                        Default: false
    + preserve (optional, boolean) - Keep existing tables in the workspace, otherwise the workspace will be purged before loading
        Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "input": [
                    {
                        "source": "in.c-application-testing.carseats",
                        "destination": "table1"
                    },
                    {
                        "source": "in.c-application-testing.cashier-data",
                        "destination": "table2"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            {
                "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": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Load Data into Development Branch Workspace [POST /v2/storage/branch/{branch_id}/workspaces/{workspace_id}/load]
Loads tables from Storage into a Workspace in [Development Branch](#reference/development-branches). Not supported for BigQuery backend.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (required, number)

+ Attributes
    + input[] (required, array) - Mappings of source tables with destinations to be loaded into the workspace
        + Items
            + (object)
                + Properties
                    + source (optional) - Required for loading table. Full table identifier of the source table (e.g.: in.c-bucket.mytable)
                    + sourceBranchId (optional) - Branch ID where to load the `source` from. If not provided, default branch will be used. Applicable when loading from `source` only.
                    + dataFileId (optional, number) - Required for loading file. File upload id. Can be used only to load file to file workspace.
                    + destination (required) - Destination table name or folder for file workspace
                    + rows (optional, number) - Limits the number of returned rows
                    + seconds (optional, number) - **Deprecated** (use changedSince and changedUntil instead). Returns rows created or updated in the last X seconds.
                    + changedSince (optional) - Currently only supported for Snowflake - Filtering by import date - timestamp of import is stored within each row. Both until and since values can be a unix timestamp.
                        **If the `days` or `seconds` parameter is set, this value is ignored.**
                    + changedUntil (optional) - Currently only supported for snowflake - Filtering by import date - timestamp of import is stored within each row. Both until and since values can be a unix timestamp.
                        **If the `days` or `seconds` parameter is set, this vallue are ignored.**
                    + columns[] (optional, array) - Array of column definition; by default all columns are exported.
                        + Items
                            + (object)
                                + Properties
                                    + source (required, string) - Column name
                                    + destination (optional, string) - Destination column name. If not set, source column name will be used.
                                    + type (required, string) - Data type, eg. VARCHAR
                                    + length (optional, string) - Data type size, where applicable, eg. 255 for VARCHAR or 10,2 for NUMBER
                                    + nullable (optional, boolean) - Allow NULL values in destination table
                                        Default: true
                                    + convertEmptyValuesToNull (optional, boolean) - Empty values replaced by NULL
                                        Default: false

                    + whereColumn (optional) - **Deprecated** (use whereFilters instead). Column for [filtering](#reference/tables/unload-data-asynchronously/asynchronous-export)
                    + whereValues[] (optional) - **Deprecated** (use whereFilters instead). Values for filtering
                    + whereOperator (optional, enum[string]) - **Deprecated** (use whereFilters instead). Comparison operator
                        + Members
                            + eq - Equal to
                            + ne - Not equal to
                        + Default: eq
                    + whereFilters (optional, array[WhereFiltersObject])
                    + incremental (optional, boolean) - Rows will be appended to an existing table, not supported in file workspaces (load is always full)
                        Default: false
                    + overwrite (optional, boolean) - When preserve is true duplicate tables will be overwritten
                        Default: false
                    + loadType (optional, enum[string]) - Select load type. Default: COPY. Use AUTO to let Storage API decide the best load type. Copy will be used always when filters, columns, or incremental are set. Clone is supported on Snowflake and BigQuery backends and accepts only "source", "destination", "overwrite" and "dropTimestampColumn" options. Clone is not supported with incremental loading or for linked buckets on BigQuery. View load type is experimental for SNFLK requires feature `input-mapping-read-only-storage`, aliases are not supported, for BigQuery working without feature, aliases are not supported. View will be created in workspace instead of loading table (View accepts only "source","destination" and "overwrite" options).
                        + Members
                            + COPY
                            + CLONE
                            + VIEW
                            + AUTO
                    + dropTimestampColumn (optional, boolean) - (CLONE loadType only) When true _timestamp column is removed after table load
                        Default: false
    + preserve (optional, boolean) - Keep existing tables in the workspace, otherwise the workspace will be purged before loading
        Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "input": [
                    {
                        "source": "in.c-application-testing.carseats",
                        "destination": "table1"
                    },
                    {
                        "source": "in.c-application-testing.cashier-data",
                        "destination": "table2"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            {
                "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": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }


## DEPRECATED: Load Data using CLONE [/v2/storage/branch/{branch_id}/workspaces/{workspace_id}/load-clone]

**Deprecated use /load endpoint with loadType:CLONE**

### Load Data using CLONE [POST /v2/storage/branch/{branch_id}/workspaces/{workspace_id}/load-clone]
**Deprecated use /load endpoint with loadType:CLONE**

Load tables from Storage into a Workspace using zero-copy cloning. Supported on Snowflake and BigQuery backends.
This load type does not support any filtering, processing parameters, or incremental loading.
Linked buckets are not supported on BigQuery.

The cloned table is an exact copy of the source table, including the `_timestamp` system column.

+ Parameters

    + workspace_id (required, number)

+ Attributes
    + input[] (required, array) - Mappings of source tables with destinations to be loaded into the workspace
        + Items
            + (object)
                + Properties
                    + source (required) - Full table identifier of the source table (e.g.: in.c-bucket.mytable)
                    + sourceBranchId (optional) - Branch ID where to load the `source` from. If not provided, default branch will be used. Applicable when loading from `source` only.
                    + destination (required) - Destination table name
                    + overwrite (optional, boolean) - When preserve is true duplicate tables will be overwritten
                        Default: false
                    + dropTimestampColumn (optional, boolean) - When true _timestamp column is removed after table load
                        Default: false
    + preserve (optional, boolean) - Keep existing tables in the workspace, otherwise the workspace will be purged before loading
        Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "input": [
                    {
                        "source": "in.c-application-testing.cashier-data",
                        "destination": "my-table"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            {
                "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": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }

## Export Table from Workspace [/v2/storage/workspaces/{workspace_id}/table-export]

### Export Table from Workspace [POST /v2/storage/workspaces/{workspace_id}/table-export]

Export a table from a workspace to file storage. This endpoint creates an asynchronous job that exports the specified table
from the workspace schema to file storage. The exported file can then be downloaded using the file ID returned in the job results.

**Note:** Supported for Snowflake and BigQuery workspaces.

+ Parameters
    + workspace_id (required, number) - The workspace ID

+ Attributes
    + tableName (required, string) - Name of the table to export from the workspace
    + fileName (optional, string) - Custom filename for the exported file. If not provided, a default filename will be generated.
    + fileType (optional, enum[string]) - File type of the exported file
        + Members
            + csv - Export as CSV format
            + parquet - Export as Parquet format (requires project feature support)
        + Default: csv
    + gzip (optional, boolean) - If true, the exported file will be gzip-compressed. Defaults to false.

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "tableName": "my_table",
                "fileName": "custom_export",
                "fileType": "csv",
                "gzip": true
            }

+ Response 202 (application/json)
    + Body

            {
                "id": 12345678,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/12345678",
                "tableId": null,
                "operationName": "workspaceTableExport",
                "operationParams": {
                    "workspaceId": 504345774,
                    "tableName": "my_table",
                    "fileName": "custom_export.csv",
                    "format": "csv",
                    "gzip": true
                },
                "createdTime": "2025-10-12T21:43:00+0000",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "user@example.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

+ Response 404 (application/json)

    Workspace not found

    + Body

            {
                "error": "Workspace \"999999\" not found",
                "code": 404
            }

+ Response 400 (application/json)

    Table not found in workspace or workspace is not a table workspace

    + Body

            {
                "error": "Table \"non_existent_table\" not found in workspace \"504345774\"",
                "code": 400
            }


            }


### Load Data using CLONE into Development Branch Workspace [POST /v2/storage/branch/{branch_id}/workspaces/{workspace_id}/load-clone]
**Deprecated use /load endpoint with loadType:CLONE**

Load tables from Storage into a Workspace in [Development Branch](#reference/development-branches) using zero-copy cloning. Supported on Snowflake and BigQuery backends.
This load type does not support any filtering, processing parameters, or incremental loading.
Linked buckets are not supported on BigQuery.

The cloned table is an exact copy of the source table, including the `_timestamp` system column.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (required, number)

+ Attributes
    + input[] (required, array) - Mappings of source tables with destinations to be loaded into the workspace
        + Items
            + (object)
                + Properties
                    + source (required) - Full table identifier of the source table (e.g.: in.c-bucket.mytable)
                    + destination (required) - Destination table name
                    + overwrite (optional, boolean) - When preserve is true duplicate tables will be overwritten
                        Default: false
    + preserve (optional, boolean) - Keep existing tables in the workspace, otherwise the workspace will be purged before loading
        Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "input": [
                    {
                        "source": "in.c-application-testing.cashier-data",
                        "destination": "my-table"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            {
                "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": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

## Password Reset [/v2/storage/workspaces/{workspace_id}/password]
### Password Reset  [POST]
Generates new password for the given workspace, for file workspace new token with 24hours expiration is issued previously created tokens has to expire and can't be reset.

+ Parameters
    + workspace_id (number)

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 201 (application/json)

    + Body

            {
                "password": "2Fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
            }

+ Response 201 (application/json)
Only for BigQuery workspace
   + Body

            {
              "credentials": {
                "type": "service_account",
                "project_id": "123456789",
                "private_key_id": "xxx",
                "private_key": "-----BEGIN PRIVATE KEY-----<key contents>-----END PRIVATE KEY-----\\n",
                "client_email": "something@else.iam.gserviceaccount.com",
                "client_id": "123456789",
                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
                "token_uri": "https://oauth2.googleapis.com/token",
                "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
                "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/something"
              }
            }


### Development Branch Workspace Password Reset [POST /v2/storage/branch/{branch_id}/workspaces/{workspace_id}/password]
Generates new password for the given workspace in [Development Branch](#reference/development-branches), for file workspace new token with 24hours expiration is issued previously created tokens has to expire and can't be reset.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (number)

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 201 (application/json)

    + Body

            {
                "password": "2Fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
            }

+ Response 201 (application/json)
Only for BigQuery workspace
   + Body

            {
              "credentials": {
                "type": "service_account",
                "project_id": "123456789",
                "private_key_id": "xxx",
                "private_key": "-----BEGIN PRIVATE KEY-----<key contents>-----END PRIVATE KEY-----\\n",
                "client_email": "something@else.iam.gserviceaccount.com",
                "client_id": "123456789",
                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
                "token_uri": "https://oauth2.googleapis.com/token",
                "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
                "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/something"
              }
            }

## Workspace set public-key [/v2/storage/workspaces/{workspace_id}/public-key]
### Workspace set public-key [POST]
Set public key for workspace user. Supported only on Snowflake. Snowflake supports two public keys to exists, when api is called either new key is created or older one is replaced.

+ Parameters
    + workspace_id (number)

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 201 (application/json)

    + Body

            {
                "publicKey": "-----BEGIN PUBLIC KEY-----...",
            }

+ Response 200 (application/json)

    + Attributes (Workspace)


### Development Branch Workspace set public-key [POST /v2/storage/branch/{branch_id}/workspaces/{workspace_id}/public-key]
Set public key for workspace user in [Development Branch](#reference/development-branches). Supported only on Snowflake. Snowflake supports two public keys to exists, when api is called either new key is created or older one is replaced.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (number)

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 201 (application/json)

    + Body

            {
                "publicKey": "-----BEGIN PUBLIC KEY-----...",
            }

+ Response 200 (application/json)

    + Attributes (Workspace)


## Workspace set public-key by name [/v2/storage/workspaces/{workspace_id}/public-key/{key_name}]
### Workspace set public-key by name [POST]
Set specific public key for workspace user. Supported only on Snowflake. Snowflake supports two public keys to exists, when api is called either new key is created or older one is replaced.

+ Parameters
    + workspace_id (number)
    + key_name (number)
    + key_name (enum[string])
        + Members
            + RSA_PUBLIC_KEY
            + RSA_PUBLIC_KEY_2

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 201 (application/json)

    + Body

            {
                "publicKey": "-----BEGIN PUBLIC KEY-----...",
            }

+ Response 200 (application/json)

    + Attributes (Workspace)


### Development Branch Workspace set public-key by name [POST /v2/storage/branch/{branch_id}/workspaces/{workspace_id}/public-key/{key_name}]
Set specific public key for workspace user in [Development Branch](#reference/development-branches). Supported only on Snowflake. Snowflake supports two public keys to exists, when api is called either new key is created or older one is replaced.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (number)
    + key_name (enum[string])
        + Members
            + RSA_PUBLIC_KEY
            + RSA_PUBLIC_KEY_2

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 201 (application/json)

    + Body

            {
                "publicKey": "-----BEGIN PUBLIC KEY-----...",
            }

+ Response 200 (application/json)

    + Attributes (Workspace)


## Execute Query [/v2/storage/branch/{branch_id}/workspaces/{workspace_id}/query]
### Execute Query [POST]

Executes a native Snowflake/BigQuery SQL query in given workspace directly without any validation or checks. Query can contain
only one SQL statement per request. Every request is new  session. Response has a different format for SELECT
query, non-SELECT query and failed query.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (required, number)

+ Attributes
    + query (required, string) - Snowflake SQL query


+ Request (application/json)
    + Headers
        X-StorageApi-Token: your_token

    + Body
        {
            "query": "SELECT * FROM table_name"
        }

+ Response 200 (application/json)

    + Body
        // Executing query (SELECT)
        {
            "status": "ok",
            "data":  {
                "columns": [
                    "ID",
                    "NAME"
                ],
                "rows": [
                    {
                        "ID": '8',
                        "NAME": "Lisa Simpson",
                    },
                    {
                        "ID": '10',
                        "NAME": "Bart Simpson",
                    }
                ]
            }
        }

        // Executing statement (non-SELECT)
        {
            "status": "ok",
            "message": "5 rows affected."
        }

        // Execution failed (Snowflake error message)
        {
            "status": "error",
            "message": "An exception occurred while executing a query: SQL compilation error: error line 1 at position 7 invalid identifier 'BIRTHDATE'"
        }


## Workspace credentials [/v2/storage/workspaces/{workspaceId}/credentials]

Manage dedicated workspace credentials to be used in Query Service
### Create credentials [POST]

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
            }

+ Response 200 (application/json)

        {
            "id": 254,
            "type": "table",
            "name": "WORKSPACE_123",
            "component": null,
            "configurationId": 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"
            },
            "readOnlyStorageAccess": true,
            "platformUsageType": "user"
        }



Create new or fetch existing credentials for dedicated workspace.

### Credentials detail [GET /v2/storage/workspaces/{workspaceId}/credentials/{id}]

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

+ Response 204 (application/json)

            {
            "id": 254,
            "type": "table",
            "name": "WORKSPACE_123",
            "component": null,
            "configurationId": 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"
            },
            "readOnlyStorageAccess": true,
            "platformUsageType": "user"
        }

Get details of specified workspace credentials

### Delete credentials [DELETE /v2/storage/workspaces/{workspaceId}/credentials/{id}]

Delete specified workspace credentials. User will be invalidated


+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

+ Response 204 (application/json)



## Workspace Unload [/v2/storage/workspaces/{workspace_id}/unload]

### Unload workspace data [POST]

Validates Snowflake transformation component configuration and examines output mapping strategies for direct-grant tables.
Returns an array of jobs instead of a single job.

+ Parameters
    + workspace_id (required, number) - Workspace ID

+ Attributes
    + only-direct-grants (optional, boolean) - Will unload only tables with direct-grant unload strategy no others.
        Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

+ Response 202 (application/json)
    + Body

            [
                {
                    "id": 75682260,
                    "status": "created",
                    "url": "https://connection.keboola.com/v2/storage/jobs/75682260",
                    "tableId": null,
                    "operationName": "workspaceUnload",
                    "operationParams": {
                        "workspaceId": "504345774",
                        "table": {
                            "source": "out.c-bucket.table1",
                            "outputMappingStrategy": "direct-grant"
                        },
                        "onlyDirectGrants": false
                    },
                    "createdTime": "2025-10-22T10:15:52+0200",
                    "startTime": null,
                    "endTime": null,
                    "runId": null,
                    "results": null,
                    "creatorToken": {
                        "id": "27978",
                        "description": "user@keboola.com"
                    },
                    "metrics": {
                        "inCompressed": false,
                        "inBytes": 0,
                        "inBytesUncompressed": 0,
                        "outCompressed": false,
                        "outBytes": 0,
                        "outBytesUncompressed": 0
                    }
                }
            ]

## Workspace Objects [/v2/storage/branch/{branch_id}/workspaces/{workspace_id}/objects]

### List Development Branch Workspace Objects [GET]

Returns a list of objects (tables and views) present in the workspace schema in [Development Branch](#reference/development-branches). Supported on Snowflake and BigQuery backends.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (required, number) - Workspace ID

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

    + Body

            [
                {
                    "name": "MY_TABLE",
                    "type": "table"
                },
                {
                    "name": "MY_VIEW",
                    "type": "view"
                }
            ]

+ Response 404 (application/json)

+ Response 422 (application/json)

    Returned when the workspace backend is not supported.

## Batch Delete Development Branch Workspace Objects [/v2/storage/branch/{branch_id}/workspaces/{workspace_id}/objects/batch-delete]

### Batch Delete Development Branch Workspace Objects [POST]

Deletes multiple tables and views from a workspace in a [Development Branch](#reference/development-branches) in a single async operation. Returns a job. All objects are attempted even if some fail, but the job will be marked as failed if any deletion fails.

+ Parameters
    + branch_id (required) - Id of the development branch
    + workspace_id (required, number) - Workspace ID

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "objects": ["MY_TABLE", "MY_VIEW"]
            }

+ Response 202 (application/json)

    + Body

            {
                "id": 12345,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/12345",
                "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"
                }
            }

+ Response 400 (application/json)

    Returned when the request body is invalid (e.g. empty objects list).

+ Response 404 (application/json)

    Returned when the workspace is not found.


## Data Structures

### Workspace

+ id: 234 (number)
+ name: `boring_wozniak` (string) - working schema name
+ type: `file|table` (string) - workspace type
+ component: `wr-db` (string, nullable) - name of the [registered component](#reference/miscellaneous/api-index/component-list) that created the workspace
+ configurationId: `aws-1` (string, nullable) - id of a [configuration](#reference/components-and-configurations/component-configurations/list-configurations) used to create workspace
+ created: `2016-05-17T11:11:20+0200` (string)
+ backendSize: `small` (string, nullable) - string for backends supporting dynamic backend size (currently only Snowflake), null for other backends
+ statementTimeoutSeconds: 0 (number) - statement timeout in seconds (only Snowflake)
+ connection
    + backend: `snowflake` (string)
    + host: `keboola.snowflakecomputing.com` (string)
    + region: `us-east1` (string)
    + database: `keboola_123` (string)
    + schema:  `boring_wozniak` (string)
    + warehouse: `SAPI_PROD` (string)
    + user: `xzy` (string)
    + container: file workspace containerName (string) - Only for file workspaces
    + loginType: `default` (string)
+ creatorToken
    + id: 234 (number)
    + description: `martin@keboola.com` (string)
+ creatorUser
    + id: 234 (number)
    + name: `Martin` (string)
+ readOnlyStorageAccess: `true` (boolean, nullable) - has read only access to storage (null when unknown).
+ platformUsageType: `user` (string, nullable) - type of usage in Keboola Connection (user, system)
+ ssoLoginAvailable: `false` (boolean) - indicates whenever is login into workspace possible via Snowflake SSO

### WorkspaceCreated (Workspace)

+ connection
    + backend: snowflake (string)
    + host: keboola.snowflakecomputing.com (string)
    + region: `us-east1` (string)
    + database: keboola_123 (string)
    + schema:  boring_wozniak (string)
    + warehouse: SAPI_PROD (string)
    + user: xzy (string)
    + password: abc (string) - Password is not stored and is returned only after workspace creation
    + connectionString: `BlobEndpoint=https://<account>.blob.core.windows.net;SharedAccessSignature=sv=2017-11-09&sr=c&st=2020-11-03T10:31:36Z&se=2020-11-04T10:31:36Z&sp=rwl&sig=<SAS signature>` (string) only for file workspaces
    + credentials(GCPCredentials) only for BigQuery workspace
    + container: file workspace containerName (string) - Only for file workspaces
    + loginType: `default` (string)

# Group Events
Virtually every interaction of the client (an API call) creates an Event. Apart from that, external events may
also be added via an API. Events are stored for a limited time.
You can access all events created on an account.

Id field is deprecated and will be removed in the future. Please use Uuid instead.

Events can be filtered by various filters:
- `sinceId`, `maxId` - Events newer or older than the passed id or Uuid (id is deprecated and will be removed in the future)
- `component` - Component name
- `configurationId` - Configuration id
- `runId` - Run id
- `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)

The events pagination uses two parameters:
- `limit` - Number of returned events. The default value: 100
- `offset` - Pagination offset

Selected of events endpoints can be used with `default` for `branch_id` parameter and emulate call endpoint without development branch.
It means that endpoint `GET /v2/storage/events` is the same as `GET /v2/storage/branch/default/events`.

## Events [/v2/storage/events]
### Create Event [POST]
Creates a new external event. The maximum allowed size of an event is 200KB. If this is exceeded,
the HTTP 400 response code is returned.

+ Attributes
    + message (required) - Event message
    + component (required) - Name of a [registered component](#reference/miscellaneous/api-index/component-list)
    + description (optional) - Event description
    + type (optional, enum[string]) - Type of the event
        + Members
            + info
            + success
            + warn
            + error
        + Default: info
    + configurationId (optional) - Id of a configuration executed by the component
    + params (optional, object) - Custom data
    + results (optional, object) - Custom data
    + duration (optional, number) - Duration of the associated task in seconds
    + runId (optional) - Id of the associated component job

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "component": "keboola.test-component",
                "message": "This is a word of warning",
                "type": "warn",
                "params": {
                    "command": "sync-test"
                },
                "results": {
                    "projectId": "123",
                    "otherId": "456"
                }
            }

+ Response 201 (application/json)
    + Body

            {
                "id": "13008826",
                "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3"
            }

### Create Development Branch Event [POST /v2/storage/branch/{branch_id}/events]
Creates a new external event for [Development Branch](#reference/development-branches). The maximum allowed size of an event is 200KB. If this is exceeded,
the HTTP 400 response code is returned.

+ Parameters
    + branch_id (required) - Id of the development branch

+ Attributes
    + message (required) - Event message
    + component (required) - Name of a [registered component](#reference/miscellaneous/api-index/component-list)
    + description (optional) - Event description
    + type (optional, enum[string]) - Type of the event
        + Members
            + info
            + success
            + warn
            + error
        + Default: info
    + configurationId (optional) - Id of a configuration executed by the component
    + params (optional, string) - Serialized JSON object with custom data
    + results (optional, string) - Serialized JSON object with custom data
    + duration (optional, number) - Duration of the associated task in seconds
    + runId (optional) - Id of the associated component job

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "component": "keboola.test-component",
                "message": "This is a word of warning",
                "type": "warn"
            }

+ Response 201 (application/json)
    + Body

            {
                "id": "13008826",
                "uuid": "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3"
            }

### Events list [GET /v2/storage/events?sinceId={sinceId}&maxId={maxId}&component={component}&configurationId={configurationId}&runId={runId}&q={q}&limit={limit}&offset={offset}]
For admin tokens will endpoint lists all events in the project. For non-admin tokens will list only events created by the token.

+ Parameters
    + sinceId (optional) - Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).
    + maxId (optional) - Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).
    + component (optional) - Shows only events emitted by the specified component.
    + configurationId (optional) - Show only events related to given configuration Id.
    + runId (optional) - Shows only events with the specified run Id.
    + q (optional) - 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).
    + limit (optional, number) - Pagination limit. Maximum allowed value is `10000`
        + Default: 100
    + offset (optional, number) - Pagination offset
        + Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Attributes (array[Event])

### Development Branch Events list [GET /v2/storage/branch/{branch_id}/events?sinceId={sinceId}&maxId={maxId}&component={component}&configurationId={configurationId}&runId={runId}&q={q}&limit={limit}&offset={offset}]
For admin tokens will endpoint lists all events in the project for [Development Branch](#reference/development-branches). For non-admin tokens will list only events created by the token in branch.

+ Parameters
    + branch_id (required) - Id of the development branch
    + sinceId (optional) - Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).
    + maxId (optional) - Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).
    + component (optional) - Shows only events emitted by the specified component.
    + configurationId (optional) - Show only events related to given configuration Id.
    + runId (optional) - Shows only events with the specified run Id.
    + q (optional) - 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).
    + limit (optional, number) - Pagination limit. Maximum allowed value is `10000`
        + Default: 100
    + offset (optional, number) - Pagination offset
        + Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Attributes (array[Event])

### Event detail [GET /v2/storage/events/{event_id}]
Obtains information about a event in the project.

+ Parameters
    + event_id (required) - Event Id or uuid (id is deprecated and will be removed in the future).

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Attributes (Event)


### Development Branch Event detail [GET /v2/storage/branch/{branch_id}/events/{event_id}]
Obtains information about a event for [Development Branch](#reference/development-branches) in the project.

+ Parameters
    + branch_id (required) - Id of the development branch
    + event_id (required) - Event Id or uuid (id is deprecated and will be removed in the future).

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Attributes (Event)


## List Bucket Events [/v2/storage/buckets/{bucket_id}/events?sinceId={sinceId}&maxId={maxId}&component={component}&configurationId={configurationId}&runId={runId}&q={q}&limit={limit}&offset={offset}]
### Bucket events list [GET]
Lists all events associated with a particular bucket.

+ Parameters
    + sinceId (optional) - Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).
    + maxId (optional) - Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).
    + component (optional) - Shows only events emitted by the specified component.
    + configurationId (optional) - Shows only events related to given configuration Id.
    + runId (optional) - Shows only events with the specified run Id.
    + q (optional) - 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).
    + limit (optional, number) - Pagination limit
        + Default: 100
    + offset (optional, number) - Pagination offset
        + Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
   + Attributes (array[Event])

## List Table Events [/v2/storage/tables/{table_id}/events?sinceId={sinceId}&maxId={maxId}&component={component}&configurationId={configurationId}&runId={runId}&q={q}&limit={limit}&offset={offset}]
### Table events list [GET]
Lists all events associated with a particular table.

+ Parameters
    + sinceId (optional) - Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).
    + maxId (optional) - Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).
    + component (optional) - Shows only events emitted by the specified component.
    + configurationId (optional) - Shows only events related to the given configuration Id.
    + runId (optional) - Shows only events with the specified run Id.
    + q (optional) - 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).
    + limit (optional, number) - Pagination limit
        + Default: 100
    + offset (optional, number) - Pagination offset
        + Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
   + Attributes (array[Event])

## List Token Events [/v2/storage/tokens/{token_id}/events?sinceId={sinceId}&maxId={maxId}&component={component}&configurationId={configurationId}&runId={runId}&q={q}&limit={limit}&offset={offset}]
### Token events list [GET]
Lists all events associated with a particular token.

+ Parameters
    + sinceId (optional) - Shows only events after the specified Id or Uuid (id is deprecated and will be removed in the future).
    + maxId (optional) - Shows only events before the passed Id or Uuid (id is deprecated and will be removed in the future).
    + component (optional) - Shows only events emitted by the specified component.
    + configurationId (optional) - Shows only events related to the given configuration Id.
    + runId (optional) - Shows only events with the specified run Id.
    + q (optional) - 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).
    + limit (optional, number) - Pagination limit
        + Default: 100
    + offset (optional, number) - Pagination offset
        + Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
   + Attributes (array[Event])

## Data Structures

### Event
+ id: 498839405 - Event Id (deprecated and will be removed in the future)
+ uuid: "01958f48-b1fc-7f05-b9b9-8a4a7b385bc3" - event uuid v7 identifier
+ event: storage.workspaceLoaded - Event identifier such as `storage.tableImportDone` or `storage.tableDetail`
+ component: storage - Name of the component that logged the event. Events can be logged by the `storage` component or any other
[registered component](#reference/miscellaneous/api-index/component-list).
+ message: `Table in.c-application-testing.cashier-data was loaded to the workspace workspace_78423 as my-table.` - Human readable description of the event
+ description: `` - Additional description of the event, such as a detailed error description
+ type: `info` (enum[string]) - Type of an event
    + Members
        + info
        + success
        + warn
        + error
+ runId: null - Id of an associated job.
+ created: `2017-02-13T16:42:00+0100` - Datetime when the event was created.
+ configurationId: null - Id of a [configuration](#reference/components-and-configurations/component-list) used by an external component.
+ objectId: `in.c-application-testing.cashier-data` - Id of the target object of the event - e.g. *id* of table for `storage.tableImportDone event`.
+ objectName: `cashier-data` - Name of the target object - e.g. a *table name* for a `storage.tableImportDone` event.
+ objectType: table - Type of the target object - e.g. *table* for the `storage.tableImportDone` event.
+ context (object) - Details about the origin of the API call that triggered the event
    + remoteAddr
    + httpReferer
    + httpUserAgent
    + apiVersion
    + userAgent
    + async (boolean)
+ params (object) - Arbitrary parameters associated with the event - e.g. CSV file settings for table import
+ results (object) - Arbitrary results of the event
+ performance (object) - Arbitrary performance metrics associated with the event
+ token (object) - Creator of the event
    + id: 1234 - Id of the token
    + name: support@keboola.com - Token owner
+ idBranch: null - Id of the development branch
+ uri: 498839405 - Event URI.
+ attachments (object) - Arbitrary list of attached files - e.g. backups for table import events
    + id (number)
    + isSliced (boolean)
    + uploadType
    + isExpired (boolean)
    + created
    + name
    + url
    + sizeBytes (number)

# Group Metadata
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 attributes 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.

## Bucket Metadata [/v2/storage/buckets/{bucket_id}/metadata]

### Create or Update [POST]
Sets multiple metadata with one call. If the given key and provider combination already exist
for the bucket, the data will be updated with the new value and timestamp. All metadata associated
with the bucket are returned in the response.

+ Parameters
    + bucket_id (required) - Id of the bucket

+ Attributes
    + provider (required) - Id of the creating [component](#reference/miscellaneous/api-index/component-list)
    + metadata (required, array) - Array of metadata objects
        + (object)
            + key (required)
            + value (required)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "provider": "test-component",
                "metadata": [
                    {
                        "key": "some-key",
                        "value": "Some value"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            [
                {
                    "id": "19509",
                    "key": "some-key",
                    "value": "Some value",
                    "provider": "test-component",
                    "timestamp": "2017-02-13 23:36:10"
                }
            ]

### List [GET]
Metadata can be listed for your bucket column.

+ Parameters
    + bucket_id (required) - Id of the bucket

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "123"
                    "provider": "keboola.some-komponent",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "attribute_key",
                    "value": "attribute_value"
                },
                {
                    "id": "124"
                    "provider": "keboola.some-komponent",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "another_attribute_key",
                    "value": "attribute_value"
                }
            ]

### Delete [DELETE /v2/storage/buckets/{bucket_id}/metadata/{metadata_id}]
Deletes the specified metadata item from the bucket.

+ Parameters
    + bucket_id (required) - Id of the bucket
    + metadata_id (required) - Id of the metadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

## Table Metadata [/v2/storage/tables/{table_id}/metadata]

### Create or Update [POST]
Sets multiple metadata for table and columns with one call. If the given key and provider combination already exist
for the table, the data will be updated with the new value and timestamp. All metadata associated
with the table and columns are returned to the response.

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

+ Parameters
    + table_id (string, required) - Id of the table

+ Attributes
    + provider (string, required) - Id of the creating [component](#reference/miscellaneous/api-index/component-list)
    + metadata (optional, array) - Array of metadata objects
        + (object)
            + key (string, required)
            + value (string, required)
    + columnsMetadata (optional) - Object of columnsMetadata. Grouped by column, but indexed by int (indexing by columnName is deprecated)
        + `<columnName/int>` (required, array) - Array of metadata objects
            + (object)
                + columnName (string, optional)
                + key (string, required)
                + value (string, required)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
              "provider": "test-component",
              "metadata": [
                {
                  "key": "some-key",
                  "value": "Some value"
                }
              ],
              "columnsMetadata": {
                "id/<intIndex>": [
                  {
                    "key": "some-key",
                    "value": "Some value",
                    "columnName": "id",
                  }
                ]
              }
            }

+ Response 201 (application/json)
    + Body

            {
              "metadata": [
                {
                  "id": "19509",
                  "key": "some-key",
                  "value": "Some value",
                  "provider": "test-component",
                  "timestamp": "2017-02-13 23:36:10"
                }
              ],
              "columnsMetadata": {
                "id": [
                  {
                    "id": "19510",
                    "key": "some-key",
                    "value": "Some value",
                    "provider": "test-component",
                    "timestamp": "2017-02-13 23:36:10"
                  }
                ]
              }
            }

### Create or Update (deprecated) [POST /v2/storage/tables/{table_id}/metadata]
***DEPRECATED**, use the endpoint [Create or Update](#reference/metadata/table-metadata/create-or-update).*

Sets multiple metadata with one call. If the given key and provider combination already exist
for the table, the data will be updated with the new value and timestamp. All metadata associated
with the table are returned to the response.

+ Parameters
    + table_id (required) - Id of the table

+ Attributes
    + provider (required) - Id of the creating [component](#reference/miscellaneous/api-index/component-list).
    + metadata (required, array) - Array of metadata objects
        + (object)
            + key (required)
            + value (required)

+ Request (application/x-www-form-urlencoded)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            provider=test-component&metadata%5B0%5D%5Bkey%5D=some-key&metadata%5B0%5D%5Bvalue%5D=Some+value


+ Response 201 (application/json)
    + Body

            [
                {
                    "id": "19509",
                    "key": "some-key",
                    "value": "Some value",
                    "provider": "test-component",
                    "timestamp": "2017-02-13 23:36:10"
                }
            ]

### List [GET]
Shows all metadata associated with the specified table.

+ Parameters
    + table_id (required) - Id of the table

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "123"
                    "provider": "keboola.some-komponent",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "attribute_key",
                    "value": "attribute_value"
                },
                {
                    "id": "124"
                    "provider": "keboola.some-komponent",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "another_attribute_key",
                    "value": "attribute_value"
                }
            ]

### Delete [DELETE /v2/storage/tables/{table_id}/metadata/{metadata_id}]
Deletes the specified metadata item from the table.

+ Parameters
    + table_id (required) - Id of the table
    + metadata_id (required) - Id of the metadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

## Column Metadata [/v2/storage/columns/{column_id}/metadata]

### Create or Update [POST]
Sets multiple metadata with one call. If the given key and provider combination already exist
for the column, the data will be updated with the new value and timestamp. All metadata associated
with the column are returned in the response.

+ Parameters
    + column_id (required) - Id of the table

+ Attributes
    + provider (required) - Id of the creating [component](#reference/miscellaneous/api-index/component-list)
    + metadata (required, array) - Array of metadata objects
        + (object)
            + key (required)
            + value (required)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "provider": "test-component",
                "metadata": [
                    {
                        "key": "some-key",
                        "value": "Some value"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            [
                {
                    "id": "19509",
                    "key": "some-key",
                    "value": "Some value",
                    "provider": "test-component",
                    "timestamp": "2017-02-13 23:36:10"
                }
            ]

### List [GET]
Shows all metadata associated with the specified column.

+ Parameters
    + column_id (required) - Id of the column

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "123"
                    "provider": "keboola.some-komponent",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "attribute_key",
                    "value": "attribute_value"
                },
                {
                    "id": "124"
                    "provider": "keboola.some-komponent",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "another_attribute_key",
                    "value": "attribute_value"
                }
            ]

### Delete [DELETE /v2/storage/columns/{column_id}/metadata/{metadata_id}]
Deletes the specified metadata item from the column.

+ Parameters
    + column_id (required) - Id of the column
    + metadata_id (required) - Id of the metadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

## Components Configurations Metadata [/v2/storage/branch/{branchId}/components/{componentId}/configs/{configId}/metadata]

All 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](#reference/development-branches/branches/list-branches) and finding branch with  attribute `isDefault` set to `true`.

### Create or Update [POST]
Sets multiple metadata with one call. If the given key and provider combination already exist
for the configuration, the data will be updated with the new value and timestamp. All metadata associated
with the configuration are returned in the response.

+ Parameters
    + branchId (required) - Id of the development branch
    + componentId (required) - Id of the Component
    + configId (required) - Id of the configuration

+ Attributes
    + metadata (array,required) - Array of metadata objects
        + (object)
            + key (required)
            + value (required)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "metadata": [
                    {
                        "key": "some-key",
                        "value": "Some value"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            [
                {
                    "id": "19509",
                    "key": "some-key",
                    "value": "Some value",
                    "timestamp": "2017-02-13 23:36:10"
                }
            ]

### List [GET]
Metadata can be listed for your component configuration.

+ Parameters
    + branchId (required) - Id of the development branch
    + componentId (required) - Id of the Component
    + configId (required) - Id of the configuration

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "123",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "attribute_key",
                    "value": "attribute_value"
                },
                {
                    "id": "124",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "another_attribute_key",
                    "value": "attribute_value"
                }
            ]

### Delete [DELETE /v2/storage/branch/{branchId}/components/{componentId}/configs/{configId}/metadata/{metadataId}]
Deletes the specified metadata item from the component configuration.

+ Parameters
    + branchId (required) - Id of the development branch
    + componentId (required) - Id of the Component
    + configId (required) - Id of the configuration
    + metadataId (required) - Id of the metadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204


## Development Branch Metadata [/v2/storage/branch/{branchId}/metadata]

All 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](#reference/development-branches/branches/list-branches) and finding branch with  attribute `isDefault` set to `true`.
Or you can use placeholder `default` to use with project's default branch.

### Create or Update [POST]
Sets multiple metadata with one call. If the given key and provider combination already exist
for the branch, the data will be updated with the new value and timestamp. All metadata associated
with the branch are returned.

+ Parameters
    + branchId (required) - Id of the development branch

+ Attributes
    + metadata (array,required) - Array of metadata objects
        + (object)
            + key (required)
            + value (required)

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "metadata": [
                    {
                        "key": "some-key",
                        "value": "Some value"
                    }
                ]
            }

+ Response 201 (application/json)
    + Body

            [
                {
                    "id": "19509",
                    "key": "some-key",
                    "value": "Some value",
                    "timestamp": "2017-02-13 23:36:10"
                }
            ]

### List [GET]
Metadata can be listed for a branch.

+ Parameters
    + branchId (required) - Id of the development branch

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "123",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "attribute_key",
                    "value": "attribute_value"
                },
                {
                    "id": "124",
                    "timestamp": "2016-09-19 13:02:11",
                    "key": "another_attribute_key",
                    "value": "attribute_value"
                }
            ]

### Delete [DELETE /v2/storage/branch/{branchId}/metadata/{metadataId}]
Deletes the specified metadata item from the development branch.

+ Parameters
    + branchId (required) - Id of the development branch
    + metadataId (required) - Id of the metadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204


# Group Jobs
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](#reference/tables/load-data-asynchronously/import-data) creates
a table import job. For each new job, the Id and URL of the job is returned.

When working with jobs, follow these steps:
1. **Start the job** - Job resource is created and a URL for polling is returned.
2. **Poll job status** - Poll the job URL in a loop until the job `status` is set to `success` or `error`.
3. **Check the results** - When the job is finished, the `results` field will contain the actual result of the original request.

Available Statuses:
- `waiting` - The job is in the queue and is waiting for execution.
- `processing` - The job is being processed by a worker.
- `success` - The job is done with a success.
- `error` - The job is done with an error.

## List Jobs [/v2/storage/jobs]
### Jobs list [GET]

+ Parameters
    + limit (optional, number) - Pagination limit
        + Default: 100
    + offset (optional, number) - Pagination offset
        + Default: 0
    + storage_job_status (optional) - Filter only jobs with status. [waiting, processing, error, success]
    + excluded_storage_job_status (optional) - Filter only jobs without status. Note: not applied when storage job status used. [waiting, processing, error, success]
    + created_time (optional) - Filter jobs created in exact time.
    + created_time_from (optional) - Filter jobs created after time. Note: not applied when created time used.
    + created_time_to (optional) - Filter jobs created before time. Note: not applied when created time used.
    + start_time (optional) - Filter jobs started in exact time.
    + start_time_from (optional) - Filter jobs started after time. Note: not applied when start time used.
    + start_time_to (optional) - Filter jobs started before time. Note: not applied when start time used.
    + end_time (optional) - Filter jobs end in exact time.
    + end_time_from (optional) - Filter jobs end after time. Note: not applied when end time used.
    + end_time_to (optional) - Filter jobs end before time. Note: not applied when end time used.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "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": "ondrej.popelka@keboola.com"
                        },
                    "metrics": {
                        "inCompressed": false,
                        "inBytes": 0,
                        "inBytesUncompressed": 0,
                        "outCompressed": true,
                        "outBytes": 7168,
                        "outBytesUncompressed": 0
                    }
                }
            ]

## Manage Jobs [/v2/storage/jobs/{jobId}]
### Job detail [GET]
Retrieves information about a single job.

+ Parameters
    + jobId - Id of the job

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "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": "ondrej.popelka@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": true,
                    "outBytes": 7168,
                    "outBytesUncompressed": 0
                }
            }


# Group Files
File Storage is used for storing arbitrary files. This is used for data imported into tables and data exported
from tables. Additionally, the File storage can be used for data backup and exchange between project participants.

File Storage is heavily used for data exchange between Storage API and other components, import backups, etc.
This kind of data is not kept forever. By default, all files are stored for **15 days**. They can be stored permanently by
using the `isPermanent` parameter. Files can also be tagged to categorize file uploads. When the `X-KBC-RunId` header is
provided, it is stored as the file `runId`.

Internally, all files are stored encrypted and are private. When you access the file through the API,
a URL with one hour expiration is generated.

Large files may be split into slices (chunks). A sliced file must have the `isSliced` parameter set to `true`. In that case
the provided key (blob) points to a **manifest file**. The manifest file contains the actual list of uploaded chunks. When uploading a sliced
file, you have to use the provided key as a prefix for chunks and generate the manifest file with the list of uploaded chunks.
When a CSV file is imported into Storage Tables, there is no difference between a normal and a sliced file.

**Example:**

Assume that the [upload method](#reference/files/upload-file/) returns the following S3 key `exp-180/11/files/2014/02/25/11085.import`.
Then you can upload e.g. these files:
- exp-180/11/files/2014/02/25/11085.import001
- exp-180/11/files/2014/02/25/11085.import002
- exp-180/11/files/2014/02/25/11085.import003

Then create the following manifest file:
```
{
  "entries": [
    {"url":"s3://kbc-sapi-files-devel/exp-180/11/files/2014/02/25/11085.import001"},
    {"url":"s3://kbc-sapi-files-devel/exp-180/11/files/2014/02/25/11085.import002"},
    {"url":"s3://kbc-sapi-files-devel/exp-180/11/files/2014/02/25/11085.import003"}
  ]
}
```

And then, upload that manifest file to the key `exp-180/11/files/2014/02/25/11085.importmanifest`. See our
[Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#working-with-sliced-files)
for a more detailed guide.

## Upload File [/v2/storage/files/prepare]
### Create File Resource [POST]
This method allows you to upload a file to KBC File Storage. The upload should be done in two steps:
1. Create a new file resource (use this API call).
2. Use the provided credentials to actually upload the file data to the storage provider.

For a more detailed guide on the file upload, see the corresponding part of the
[Developers documentation](https://developers.keboola.com/integrate/storage/api/import-export/#manually-uploading-a-file).

+ Attributes
    + name (required) - File name
    + sizeBytes (optional, number) - File size in bytes
    + contentType (optional) - File [MIME Type](https://en.wikipedia.org/wiki/Media_type)
        Default: `application/octet-stream`
    + isPermanent (optional, boolean) - Keeps a file forever. If false, the file will be **deleted after 15 days**.
        Default: false
    + notify (optional, boolean) - Notifies project administrators that a file was uploaded.
        Default: false
    + tags[] (optional) - Assigns one or more tags to the file.
    + federationToken (optional, boolean) - Must be set to `true`.
        Default: false
    + isSliced (optional, boolean) - If true, multiple chunks of a file are allowed to be uploaded. Must be used with `federationToken`.
        Default: false
    + isEncrypted (optional, boolean) - If true, the file content will be encrypted in the provided storage. Azure and Google Cloud always create encrypted file regardless this setting.
        Default: false

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "someFile.csv",
                "tags": [
                    "tag1",
                    "tag2"
                ],
                "sizeBytes": 12345,
                "federationToken": true
            }

+ Response 201 (application/json)
    for Azure provider
    + Body

            {
                "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-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKI...0214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170214T093446Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=374...a4c",
                "provider": "aws",
                "region": "us-east-1",
                "sizeBytes": 12345,
                "tags": [
                    "tag1",
                    "tag2"
                ],
                "maxAgeDays": 30,
                "runId": null,
                "runIds": [],
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@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"
                    }
                }
            }

+ Response 201 (application/json)
    for Azure provider
    + Body

            {
                "id": 236518631,
                "created": "2017-02-14T10:34:45+0100",
                "isPublic": false,
                "isSliced": false,
                "isEncrypted": true,
                "name": "somefile.csv",
                "fileType": "csv",
                "url": "https://kbcfshc7chguaeh2km.blob.core.windows.net/exp-15-files-4516-27364641-2022-11-09/somefile.csv?sv=2017-11-09&sr=c&st=2022-11-09T16:55:44Z&se=2022-11-10T04:55:44Z&sp=rl&sig=tBsXf...",
                "provider": "azure",
                "region": "us-east-1",
                "sizeBytes": 12345,
                "tags": [
                    "tag1",
                    "tag2"
                ],
                "maxAgeDays": 30,
                "runId": null,
                "runIds": [],
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "absUploadParams": {
                    "blobName": "somefile.csv",
                    "accountName": "kbcfshc7chguaeh2km",
                    "container": "exp-15-files-4516-27364641-2022-11-09",
                    "absCredentials": {
                        "SASConnectionString": "BlobEndpoint=https://kbcfshc7chguaeh2km.blob.core.windows.net;SharedAccessSignature=sv=2017-11-09&sr=c&st=2022-11-09T16:55:44Z&se=2022-11-10T04:55:44Z&sp=rwl&sig=x6csI...",
                        "expiration": "2022-11-10T05:55:44+0100"
                    }
                }
            }

+ Response 201 (application/json)
    for GCP provider
    + Body

            {
                "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-Credential=ci-connection-file-storage%40ci-connection-361807.iam.gserviceaccount.com%2F20221109%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20221109T193733Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&response-content-disposition=attachment&X-Goog-Signature=57f3...",
                "provider": "gcp",
                "region": "us-east-1",
                "sizeBytes": 12345,
                "tags": [
                    "tag1",
                    "tag2"
                ],
                "maxAgeDays": 30,
                "runId": null,
                "runIds": [],
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@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"
                }
            }

## Refresh File Credentials [/v2/storage/files/{file_id}/refresh]
### Refresh File Credentials [PUT]
**Endpoint is used to generate new credentials only for files stored in GCS.**

Because for GCS the maximum lifetime of a credentials are only one hour,
so if in case of longer uploads than one hour we have to generate a new credentials with one hour validity after this time.

**We can generate new credentials up to 12h after the first creation of a file using [Create File Resource](#reference/files/upload-file)**

+ Parameters
    + file_id (required, number) - File Id


+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "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-Credential=ci-connection-file-storage%40ci-connection-361807.iam.gserviceaccount.com%2F20221109%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20221109T193733Z&X-Goog-Expires=3600&X-Goog-SignedHeaders=host&response-content-disposition=attachment&X-Goog-Signature=57f3...",
                "provider": "gcp",
                "region": "us-east-1",
                "sizeBytes": 12345,
                "tags": [
                    "tag1",
                    "tag2"
                ],
                "maxAgeDays": 30,
                "runId": null,
                "runIds": [],
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@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"
                }
            }


## List Files [/v2/storage/files?sinceId={sinceId}&maxId={maxId}&tags={tags}&q={q}&runId={runId}&limit={limit}&offset={offset}&showExpired={showExpired}]
### List Files [GET]
Lists all files uploaded by your token. If the `canReadAllFileUploads` permission is set for your token,
all file uploads for project will be returned.

*Note*: There can be a delay of up to one second before any file change is propagated into the
list of files (including addition and removal of a file).

+ Parameters
    + sinceId (optional) - Shows only files after the specified Id.
    + maxId (optional) - Shows only files before the passed Id.
    + tags (optional) - Shows only files with one or more of the specified tags.
    + q (optional) - 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).
    + runId (optional) - Shows only files with the given run Id.
    + limit (optional, number) - Pagination limit
        + Default: 100
    + offset (optional, number) - Pagination offset
        + Default: 0
    + showExpired (optional, boolean) - Include expired files in response
        Default: false

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "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-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJ2N244XSWYVVYVLQ%2F20170214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170214T094038Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=9872bf99808caf6e65bab96f8b2fb5ed9d35fa12ef33d90a56bfc6253634ffe8",
                    "region": "us-east-1",
                    "sizeBytes": 133,
                    "tags": [],
                    "maxAgeDays": 30,
                    "runId": null,
                    "runIds": [],
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    }
                }
            ]


## Manage Files [/v2/storage/files/{file_id}]
### File detail [GET /v2/storage/files/{file_id}?federationToken={federationToken}]
Returns detailed information about a single file.

+ Parameters
    + file_id (required, number) - File Id
    + federationToken (optional, boolean) - Return AWS credentials with permissions for a direct file download from S3. The credentials are valid for 12 hours.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "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-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKI...214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170214T101017Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Signature=d76...288",
                "region": "us-east-1",
                "sizeBytes": 133,
                "tags": [],
                "maxAgeDays": 30,
                "runId": null,
                "runIds": [],
                "creatorToken": {
                "id": 27978,
                    "description": "ondrej.popelka@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"
                }
            }

### Delete File [DELETE]
Deletes a file from storage.

+ Parameters
    + file_id (required, number) - File Id
    + async (optional, boolean) - Prepare file in a background job. Calling the parameter as `async=false` is deprecated.


+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204
    Synchronous call response without content.


+ Response 202 (application/json)
    Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

           {
               "id": 11,
               "status": "waiting",
               "url": "https://connection.keboola.com/v2/storage/jobs/11",
               "operationName": "workspaceCreate",
               "operationParams": {
                   "fileId": 1,
                   "branchId": 1
               },
               "createdTime": "2013-05-31T16:11:05+0200",
               "startTime": null,
               "endTime": null,
               "runId": null,
               "results": null,
               "creatorToken": {
                   "id": "27978",
                   "description": "roman.bracinik@keboola.com"
               },
               "metrics": {
                   "inCompressed": false,
                   "inBytes": 0,
                   "inBytesUncompressed": 0,
                   "outCompressed": false,
                   "outBytes": 0,
                   "outBytesUncompressed": 0
               }
           }

## Create Tag [/v2/storage/files/{file_id}/tags]
### Add Tag [POST]
Adds a new tag to a file.

+ Parameters
    + file_id (required, number) - File id

+ Attributes
    + tag (required) - Tag name

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "tag": "image"
            }

+ Response 204

## Manage Tags [/v2/storage/files/{file_id}/tags/{tag_name}]
### Delete Tag [DELETE]
Deletes a single tag from the specified file.

+ Parameters
    + file_id (required, number) - File id
    + tag_name (required) - Tag name

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

# Group Tickets
Tickets are unique sequential 64 bit IDs. Tickets are used to generate unique run identifiers for
all components using Keboola Connection.

## Generate Unique ID [/v2/storage/tickets/]
### Generate New Id [POST]

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 201 (application/json)
    + Body

            {
                "id": 123454352345
            }

# Group Components and Configurations

Component Configuration represents specific settings of a
[registered Component](#reference/miscellaneous/api-index/component-list)
in a project. See the [Developers Documentation](https://developers.keboola.com/integrate/storage/api/configurations/)
for examples and use cases.
This is a utility resource available only for master tokens and tokens with the `canManageBuckets` permission.
Configurations may include *Configuration Rows* if they are composed of multiple objects. Configuration rows are
used in case parts of the configuration are supposed to be updated independently.
Configurations are automatically versioned. Configuration Rows are versioned separately, but they are also recorded as
changes of the configuration. The `configuration` and
`rows.configuration` fields can contain arbitrary objects. The content and interpretation of those fields is fully
defined by the component.

All components and configurations endpoints can be used with `default` for `branch_id` parameter and emulate call endpoint without development branch.
It means that endpoint `GET /v2/storage/components` is the same as `GET /v2/storage/branch/default/components`.

## Get component [/v2/storage/components/{componentId}]
### Get component [GET /v2/storage/branch/{branch_id}/components/{componentId}]

Use this API call to obtain the definition of component for [Development Branch](#reference/development-branches) available in KBC.

+ Parameters
    + branch_id - Id of development branch
    + componentId - Component ID - e.g. `keboola.app-tree`

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200
    + Headers

            Content-type: application/json

    + Body

            {
                "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 (e.g. product categories). The tree data must be stored in a child-parent relationship. A column named **levels** will be added to the table (root nodes will have number 1). Additionally, a column named **root** will be added, containing the ID of the root item.",
                "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": {
                    "title": "Parameters",
                    "type": "object",
                    "properties": {
                        "idColumn": {
                            "type": "string",
                            "title": "ID Column",
                            "description": "Name of the column containing row identifier",
                            "default": "categoryId"
                        },
                        "parentColumn": {
                            "type": "string",
                            "title": "Parent Column",
                            "description": "Name of the column containing parent identifier",
                            "default": "categoryParentId"
                        }
                    },
                    "required": [
                        "idColumn",
                        "parentColumn"
                    ]
                },
                "emptyConfiguration": {},
                "uiOptions": {},
                "configurationDescription": "The tree data must be stored in a child-parent relationship. A column named **levels** will be added to the table (root nodes will have number 1). Additionally, a column named **root** will be added, containing the ID of the root item.\n\nSample input \n-------------------\n\ncategoryId | categoryParentId\t| title\n--- | --- | --- \n1 |\t0 | foo\n2 | 1 | bar\n3 | 1 | baz\n4 | 2 | buzz\n\n\nSample output\n-------------------\n\ncategoryId | categoryParentId | title | levels | root\n--- | --- | --- | --- | --- |\n1 |\t0 | foo | 1 | 1 |\n2 | 1 | bar | 2 | 1 |\n3 | 1 | baz | 2 | 1 |\n4 | 2 | buzz | 3 | 1 |",
                "uri": "https://syrup.keboola.com/docker/keboola.app-tree",
                "dataTypesConfiguration": {},
                "processorConfiguration": {}
            }

### Get component - without branch in URL (without authentification) [GET]

**Without authentication**, you can call this endpoint without the `X-StorageApi-Token` and still get the component details.

+ Parameters
    + componentId - Component ID - e.g. `keboola.app-tree`


+ Response 200
    + Headers

            Content-type: application/json
    + Body

            {
                "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 (e.g. product categories). The tree data must be stored in a child-parent relationship. A column named **levels** will be added to the table (root nodes will have number 1). Additionally, a column named **root** will be added, containing the ID of the root item.",
                "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": {
                    "title": "Parameters",
                    "type": "object",
                    "properties": {
                        "idColumn": {
                            "type": "string",
                            "title": "ID Column",
                            "description": "Name of the column containing row identifier",
                            "default": "categoryId"
                        },
                        "parentColumn": {
                            "type": "string",
                            "title": "Parent Column",
                            "description": "Name of the column containing parent identifier",
                            "default": "categoryParentId"
                        }
                    },
                    "required": [
                        "idColumn",
                        "parentColumn"
                    ]
                },
                "emptyConfiguration": {},
                "uiOptions": {},
                "configurationDescription": "The tree data must be stored in a child-parent relationship. A column named **levels** will be added to the table (root nodes will have number 1). Additionally, a column named **root** will be added, containing the ID of the root item.\n\nSample input \n-------------------\n\ncategoryId | categoryParentId\t| title\n--- | --- | --- \n1 |\t0 | foo\n2 | 1 | bar\n3 | 1 | baz\n4 | 2 | buzz\n\n\nSample output\n-------------------\n\ncategoryId | categoryParentId | title | levels | root\n--- | --- | --- | --- | --- |\n1 |\t0 | foo | 1 | 1 |\n2 | 1 | bar | 2 | 1 |\n3 | 1 | baz | 2 | 1 |\n4 | 2 | buzz | 3 | 1 |",
                "uri": "https://syrup.keboola.com/docker/keboola.app-tree",
                "dataTypesConfiguration": {},
                "processorConfiguration": {}
            }

## Get components [/v2/storage/components]
### Get components [GET /v2/storage/branch/{branch_id}/components?include={include}&componentType={componentType}&isDeleted={isDeleted}]
Use this API call to obtain the definitions of all components in [Development Branch](#reference/development-branches). For more information about the
KBC Component architecture, see the [Developers documentation](https://developers.keboola.com/overview/)

+ Parameters
    + branch_id (required) - Id of the development branch
    + componentType (optional) - Component type - `extractor`, `writer`, `application`, etc.
    + include (optional) - Comma separated list of resources to include. Available resources: `configuration`, `rows` and `state`.
    + isDeleted (optional, boolean) - If true, it returns only components with deleted configurations.
        Default: false

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200
    + Headers

            Content-type: application/json

    + Body

            [
                {
                    "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 (e.g. product categories). The tree data must be stored in a child-parent relationship. A column named **levels** will be added to the table (root nodes will have number 1). Additionally, a column named **root** will be added, containing the ID of the root item.",
                    "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": {
                        "title": "Parameters",
                        "type": "object",
                        "properties": {
                            "idColumn": {
                                "type": "string",
                                "title": "ID Column",
                                "description": "Name of the column containing row identifier",
                                "default": "categoryId"
                            },
                            "parentColumn": {
                                "type": "string",
                                "title": "Parent Column",
                                "description": "Name of the column containing parent identifier",
                                "default": "categoryParentId"
                            }
                        },
                        "required": [
                            "idColumn",
                            "parentColumn"
                        ]
                    },
                    "emptyConfiguration": {},
                    "uiOptions": {},
                    "configurationDescription": "The tree data must be stored in a child-parent relationship. A column named **levels** will be added to the table (root nodes will have number 1). Additionally, a column named **root** will be added, containing the ID of the root item.\n\nSample input \n-------------------\n\ncategoryId | categoryParentId\t| title\n--- | --- | --- \n1 |\t0 | foo\n2 | 1 | bar\n3 | 1 | baz\n4 | 2 | buzz\n\n\nSample output\n-------------------\n\ncategoryId | categoryParentId | title | levels | root\n--- | --- | --- | --- | --- |\n1 |\t0 | foo | 1 | 1 |\n2 | 1 | bar | 2 | 1 |\n3 | 1 | baz | 2 | 1 |\n4 | 2 | buzz | 3 | 1 |",
                    "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": "ondrej.popelka@keboola.com"
                            },
                            "version": 2,
                            "changeDescription": "Configuration deleted",
                            "isDeleted": true,
                            "currentVersion": {
                                "created": "2017-02-14T12:12:45+0100",
                                "creatorToken": {
                                    "id": 27978,
                                    "description": "ondrej.popelka@keboola.com"
                                },
                                "changeDescription": "Configuration deleted"
                            }
                        }
                    ],
                    "dataTypesConfiguration": {},
                    "processorConfiguration": {}
                }
            ]

### Get components - without branch in URL (deprecated) [GET /v2/storage/components?include={include}&componentType={componentType}&isDeleted={isDeleted}]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200

## Component Configurations [/v2/storage/components/{component_id}/configs]
### List configurations [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs?isDeleted={isDeleted}]
Lists all configurations for a component including all config rows in [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + isDeleted (optional, boolean) - When true, only deleted configurations will be returned. When false, only current configurations will be returned.
        + Default: false

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "id": "main-1",
                    "name": "Main 1",
                    "description": "",
                    "created": "2016-05-11T14:33:50+0200",
                    "creatorToken": {
                        "id": 67,
                        "description": "dev@keboola.com"
                    },
                    "version": 2,
                    "changeDescription": "Row row1 added",
                    "isDeleted": false,
                    "configuration": {
                        "key1": "val1"
                    },
                    "currentVersion": {
                        "created": "2016-05-11T14:33:50+0200",
                        "creatorToken": {
                            "id": 67,
                            "description": "dev@keboola.com"
                        },
                        "changeDescription": "Row row1 added",
                        "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N"
                    },
                    "rowsSortOrder": [],
                    "rows": [
                        {
                            "id": "row1",
                            "configuration": {
                                "key2": "val2"
                            },
                            "state": {},
                            "version": 1,
                            "created": "2016-05-11T14:33:50+0200",
                            "creatorToken": {
                                "id": 67,
                                "description": "dev@keboola.com"
                            },
                            "changeDescription": null
                        }
                    ],
                    "state": {}
                }
            ]

### Create Configuration [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs]
Creates a new component configuration for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the Component

+ Attributes
    + name (required, string) - Configuration name
    + configurationId (optional, number) - Configuration Id (must be unique for each component type). If not set, it will be auto-generated.
    + description (optional, string) - Configuration description
    + configuration (optional, object) - Configuration data; the maximum allowed size is 4MB
    + state (optional, object) - State configuration data; the maximum allowed size is 4MB
    + changeDescription (optional, string) - Description of the configuration modification
    + isDisabled (optional, boolean) - Disabled flag

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "My new configuration",
                "configuration": {
                    "key": "value",
                    "key2": "value2"
                },
                "changeDescription": "Initial configuration"
            }

+ Response 201 (application/json)
    + Body

            {
                "id": "236606822",
                "name": "My new configuration",
                "description": "",
                "created": "2017-02-14T14:38:26+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "version": 1,
                "changeDescription": "Initial configuration",
                "isDisabled": false,
                "isDeleted": false,
                "configuration": {
                    "key": "value",
                    "key2": "value2"
                },
                "state": {},
                "currentVersion": {
                    "created": "2017-02-14T14:38:26+0100",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Initial configuration",
                    "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S",
                }
            }

### List configurations - without branch in URL (deprecated) [GET /v2/storage/components/{component_id}/configs?isDeleted={isDeleted}]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

### Create Configuration - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 201 (application/json)

## Manage Configurations [/v2/storage/components/{component_id}/configs/{config_id}]
### Configuration Detail [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}]
Gets the component configuration detail for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + config_id (required) - Id of the configuration

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

            {
                "id": "236606822",
                "name": "My new configuration",
                "description": "",
                "created": "2017-02-14T14:38:26+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "version": 1,
                "changeDescription": "Initial configuration",
                "isDeleted": false,
                "configuration": {
                    "key": "value",
                    "key2": "value2"
                },
                "rowsSortOrder": [],
                "rows": [],
                "state": {},
                "currentVersion": {
                    "created": "2017-02-14T14:38:26+0100",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Initial configuration",
                    "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N"
                }
            }

### Update Configuration [PUT /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}]
Updates an existing configuration for [Development Branch](#reference/development-branches). When the configuration is updated in a development branch, it does not affect `currentVersion` of the configuration.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + config_id (required) - Id of the configuration

+ Attributes
    + name (required, string) - Configuration name
    + description (optional, string) - Configuration description
    + configuration (optional, object) - Configuration data; the maximum allowed size is 4MB
    + state (optional, object) - State configuration data; the maximum allowed size is 4MB
    + changeDescription (optional, string) - Description of the configuration modification
    + isDisabled (optional, boolean) - Disabled flag
    + rowsSortOrder (optional, array[string]) - Array of row ids in desired order, you have to specify all row ids

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "configuration": {
                    "key": "value",
                    "key2": "value2",
                    "key3": "value3"
                },
                "changeDescription": "Added new key"
            }

+ Response 200 (application/json)
    + Body

            {
                "id": "236606822",
                "name": "My new configuration",
                "description": "",
                "created": "2017-02-14T14:38:26+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "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:48:41+0100",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Added new key",
                    "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N"
                }
            }

### Update Configuration State [PUT /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/state]
Updates state of an existing configuration for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + config_id (required) - Id of the configuration

+ Attributes
    + state (required, object) - Configuration state data; the maximum allowed size is 4MB

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "state": {
                    "lastId": 123
                }
            }

+ Response 200 (application/json)
    + Body

            {
                "id": "236606822",
                "name": "My new configuration",
                "description": "",
                "created": "2017-02-14T14:38:26+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "version": 2,
                "changeDescription": "Added new key",
                "isDeleted": false,
                "configuration": {
                    "key": "value",
                    "key2": "value2",
                    "key3": "value3"
                },
                "rowsSortOrder": [],
                "rows": [],
                "state": {
                    "lastId": 123
                },
                "currentVersion": {
                    "created": "2017-02-14T14:48:41+0100",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Added new key",
                    "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N"
                }
            }

### Reset Development Branch Configuration to Default [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/reset-to-default]
Updates an existing configuration for [Development Branch](#reference/development-branches) to a version that is currently in projects default branch.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + config_id (required) - Id of the configuration

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204 (application/json)

### Delete Configuration [DELETE /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}]
Deletes a configuration in specified branch. When a configuration is deleted, it is only marked as deleted and remains still available in the system.
You can [list deleted](#reference/components-and-configurations/component-configurations/list-development-branch-configurations) configurations.
Other operations with deleted configurations are restricted.

Calling this API call on a deleted configuration in a **development branch** will result in an error. Development branch configuration cannot be permanently removed.
Calling this API call on a deleted configuration in a **default branch** will purge the configuration.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + config_id (required) - Id of the configuration

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 204

### Configuration Detail - without branch in URL (deprecated) [GET]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

### Update Configuration - without branch in URL (deprecated) [PUT]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

### Update Configuration State - without branch in URL (deprecated) [PUT /v2/storage/components/{component_id}/configs/{config_id}/state]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

### Delete Configuration - without branch in URL (deprecated) [DELETE]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 204

## Configuration Restore [/v2/storage/components/{component_id}/configs/{config_id}/restore]
### Restore Deleted Configuration [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/restore]
Removes the `isDeleted` flag of a deleted configuration for [Development Branch](#reference/development-branches). This makes a new version of the configuration
and the configuration becomes available for other API calls.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + config_id (required) - Id of the configuration

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

            {
                "id": "236606822",
                "name": "My new configuration",
                "description": "",
                "created": "2017-02-14T14:38:26+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "version": 4,
                "changeDescription": "Configuration restored",
                "isDeleted": false,
                "currentVersion": {
                    "created": "2017-02-14T15:48:39+0100",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Configuration restored",
                    "versionIdentifier": "01H2W8N0ZJJB6V126C8ZSND28N"
                }
            }

### Restore Deleted Configuration - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

## List Configuration Versions [/v2/storage/components/{component_id}/configs/{config_id}/versions]
### Versions list [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/versions?include={include}&limit={limit}&offset={offset}]

Lists all versions of a component configuration for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component
    + config_id (required) - Id of the configuration
    + include (optional) - Comma separated list of information to be retrieved; possible fields are `name`, `description` and `configuration`.
        Default: `name,description`
    + limit (optional, number) - Pagination limit
        Default: 100
    + offset (optional, number) - Pagination offset
        Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "version": 2,
                    "created": "2017-02-09T21:11:02+0100",
                    "versionIdentifier": "0001J8B6AMR2DJWHYPC5HE7BWA",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Add input table in.c-afnhk.tree-test",
                    "isDeleted": false,
                    "name": "test",
                    "description": ""
                },
                {
                    "version": 1,
                    "created": "2017-02-09T21:10:31+0100",
                    "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "",
                    "isDeleted": false,
                    "name": "test",
                    "description": ""
                }
            ]

### Versions list - without branch in URL (deprecated) [GET /v2/storage/components/{component_id}/configs/{config_id}/versions?include={include}&limit={limit}&offset={offset}]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

## Manage Configuration Versions [/v2/storage/components/{component_id}/configs/{config_id}/versions/{version_id}]
### Version Detail [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/versions/{version_id}]

Gets configuration version for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + version_id (required, string) - Version number

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "version": 1,
                "created": "2017-02-09T21:10:31+0100",
                "versionIdentifier": "01H2W7DAN0QT78NZQ2BD2BZT4S",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "changeDescription": "",
                "isDeleted": false,
                "name": "test",
                "description": "",
                "configuration": {},
                "rowsSortOrder": [],
                "rows": []
            }

### Version Detail - without branch in URL (deprecated) [GET]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

## Rollback Configuration Version [/v2/storage/components/{component_id}/configs/{config_id}/versions/{version_id}/rollback]
### Rollback Version [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/versions/{version_id}/rollback]
Rollbacking a configuration version actually creates a new configuration version identical to the
one you specified. `state` attributes of the config and rows is preserved, if any row is recreated, it will have the last existing state.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + version_id (required, number) - Version number to rollback to

+ Attributes
    + changeDescription (optional, string) - Description of a version change

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "changeDescription": "change description"
            }

+ Response 201 (application/json)

        {
            "version": 3
        }

### Rollback Version - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 201 (application/json)

## Copy Configurations [/v2/storage/components/{component_id}/configs/{config_id}/versions/{version_id}/create]
### Create Configuration Copy [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/versions/{version_id}/create]
Creates a new configuration from the specified configuration version in [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration to copy
    + version_id (required, number) - Version number to copy

+ Attributes
    + name (required, string) - Name of the new configuration
    + description (optional, string) - Description of the new configuration
    + changeDescription (optional, string) - Version change description

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "Configuration copy",
                "changeDescription": "Testing Copying"
            }

+ Response 201 (application/json)

        {
            "id": 4
        }

### Create Configuration Copy - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 201 (application/json)

## Create or List Configuration Rows [/v2/storage/components/{component_id}/configs/{config_id}/rows]
### Create Configuration Row [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows]
Creates a new row (item) of an existing configuration in [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration

+ Attributes
    + rowId (optional, string) - Row id (must be unique for each configuration); if not set, it will be generated
    + configuration (optional, object) - Configuration data; the maximum allowed size is 4MB
    + state (optional, object) - Configuration state data; the maximum allowed size is 4MB
    + name (optional, string) - Row name
    + description (optional, string) - Row description
    + isDisabled (optional, boolean) - Disabled flag
    + changeDescription (optional, string) - Version change description

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "configuration": {
                    "host": "localhost",
                    "port": 4406
                },
                "changeDescription": "Added new row"
            }

+ Response 201 (application/json)

            {
                "id": "236781646",
                "configuration": {
                    "host": "localhost",
                    "port": 4406
                },
                "state": {},
                "name": "",
                "description": "",
                "isDisabled": false,
                "version": 1,
                "created": "2017-02-15T00:05:32+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "changeDescription": "Added new row"
            }

### Configuration Row List [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows]
Gets configuration rows for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration

+ Request
    + Headers

            X-StorageApi-Token: your_token


+ Response 200 (application/json)

            [
                {
                    "id": "236781529",
                    "configuration": {},
                    "state": {},
                    "name": "",
                    "description": "",
                    "isDisabled": false,
                    "version": 1,
                    "created": "2017-02-15T00:04:42+0100",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Row 236781529 added"
                },
                {
                    "id": "236781639",
                    "configuration": {
                        "host": "localhost",
                        "port": 4406
                    },
                    "state": {},
                    "name": "",
                    "description": "",
                    "isDisabled": false,
                    "version": 1,
                    "created": "2017-02-15T00:05:29+0100",
                    "creatorToken": {
                        "id": 27978,
                        "description": "ondrej.popelka@keboola.com"
                    },
                    "changeDescription": "Added new row"
                }
            ]

### Create Configuration Row - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 201 (application/json)

### Configuration Row List - without branch in URL (deprecated) [GET]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

## Manage Configuration Rows [/v2/storage/components/{component_id}/configs/{config_id}/rows/{row_id}]
### Configuration Row detail [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}]
Gets configuration rows for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row

+ Request
    + Headers

            X-StorageApi-Token: your_token


+ Response 200 (application/json)

            {
                "id": "236781529",
                "configuration": {},
                "state": {},
                "name": "",
                "description": "",
                "isDisabled": false,
                "version": 1,
                "created": "2017-02-15T00:04:42+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "name@example.com"
                },
                "changeDescription": "Row 236781529 added",
                "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P"
            }

### Update Configuration Row [PUT /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}]
Modifies the content of a single row in [Development Branch](#reference/development-branches). Note that configuration rows are versioned
independently on the configurations.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row

+ Attributes
    + configuration (optional, object) - Configuration data; the maximum allowed size is 4MB
    + state (optional, object) - Configuration state data; the maximum allowed size is 4MB
    + name (optional, string) - Row name
    + description (optional, string) - Row description
    + isDisabled (optional, boolean) - Disabled flag
    + changeDescription (optional, string) - Version change description

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "configuration": {
                    "host": "localhost",
                    "port": null
                },
                "changeDescription": "change description"
            }

+ Response 200 (application/json)

            {
                "id": "236781529",
                "configuration": {
                    "host": "localhost",
                    "port": null
                },
                "state": {},
                "name": "",
                "description": "",
                "isDisabled": false,
                "version": 2,
                "created": "2017-02-15T00:04:42+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "changeDescription": "change description",
                "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P"
            }

### Update Configuration Row State [PUT /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}/state]
Updates state of an existing configuration for [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row

+ Attributes
    + state (required, object) - Configuration state data; the maximum allowed size is 4MB

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "state": {
                    "lastId": 123
                }
            }

+ Response 200 (application/json)

            {
                "id": "236781529",
                "configuration": {
                    "host": "localhost",
                    "port": null
                },
                "state": {
                    "lastId": 123
                },
                "name": "",
                "description": "",
                "isDisabled": false,
                "version": 2,
                "created": "2017-02-15T00:04:42+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "changeDescription": "change description",
                "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P"
            }

### Delete Configuration Row [DELETE /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}]
Deletes a configuration row for [Development Branch](#reference/development-branches).
A configuration row is deleted permanently and cannot be restored.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row

+ Attributes
    + changeDescription (optional, string) - Version change description

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "changeDescription": "change description"
            }

+ Response 204

### Configuration Row detail - without branch in URL (deprecated) [GET]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

### Update Configuration Row - without branch in URL (deprecated) [PUT]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

### Update Configuration Row State - without branch in URL (deprecated) [PUT /v2/storage/components/{component_id}/configs/{config_id}/rows/{row_id}/state]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

### Delete Configuration Row - without branch in URL (deprecated) [DELETE]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 204

## List Configuration Row Versions [/v2/storage/components/{component_id}/configs/{config_id}/rows/{row_id}/versions]
### Versions list [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}/versions?include={include}&limit={limit}&offset={offset}]
List versions of a given configuration Row of a given Configuration for [Development Branch](#reference/development-branches)

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row
    + include (optional) - Comma separated list of information to retrieve; it may contain: `configuration`
        Default: `configuration`
    + limit (optional, number) - Pagination limit
        Default: 100
    + offset (optional, number) - Pagination offset
        Default: 0

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200
    + Headers

            Content-type: application/json

    + Body

            [
                {
                    "version": 2,
                    "name": "",
                    "description": "",
                    "isDisabled": false,
                    "created": "2015-08-12T12:33:04+0200",
                    "creatorToken": {
                        "id": 1392,
                        "description": "martin@keboola.com"
                    },
                    "changeDescription": "Cause of the change",
                    "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P"
                },
                {
                    "version": 1,
                    "name": "",
                    "description": "",
                    "isDisabled": false,
                    "created": "2015-08-10T22:00:55+0200",
                    "creatorToken": {
                        "id": 1392,
                        "description": "martin@keboola.com"
                    },
                    "changeDescription": "Some other cause of the change",
                    "versionIdentifier": "01H5PWX76CG19RAKJW4Q8WMFST"
                }
            ]

### Versions list - without branch in URL (deprecated) [GET /v2/storage/components/{component_id}/configs/{config_id}/rows/{row_id}/versions?include={include}&limit={limit}&offset={offset}]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200

## Manage Configuration Row Versions [/v2/storage/components/{component_id}/configs/{config_id}/rows/{row_id}/versions/{version_id}]
### Version detail [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}/versions/{version_id}]
Gets details about the Configuration Row version.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row
    + version_id (required) - Id of the configuration row version

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "name": "",
                "description": "",
                "isDisabled": false,
                "version": 1,
                "created": "2015-08-10T22:00:55+0200",
                "creatorToken": {
                    "id": 1392,
                    "description": "martin@keboola.com"
                },
                "changeDescription": "Some other cause of the change",
                "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P"
                "configuration": {}
            }

### Version detail - without branch in URL (deprecated) [GET]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

## Rollback Configuration Row Version [/v2/storage/components/{component_id}/configs/{config_id}/rows/{row_id}/versions/{version_id}/rollback]
### Rollback Version [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}/versions/{version_id}/rollback]
Rollbacks row to a previous version. This operation actually creates a new Row version with identical
content to be rollbacked to.

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row
    + version_id (required) - Id of the configuration row version to rollback to

+ Attributes
    + changeDescription (optional, string) - Version change description

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "changeDescription": "Rollback to previous version"
            }

+ Response 201 (application/json)

            {
                "id": "236781646",
                "configuration": {
                    "host": "localhost",
                    "port": 4406
                },
                "state": {},
                "name": "",
                "description": "",
                "isDisabled": false,
                "version": 2,
                "created": "2017-02-15T00:05:32+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "changeDescription": "Rollback to previous version",
                "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P"
            }

### Rollback Version - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 201 (application/json)

## Copy Configuration Rows [/v2/storage/components/{component_id}/configs/{config_id}/rows/{row_id}/versions/{version_id}/create]
### Create Configuration Row copy [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/rows/{row_id}/versions/{version_id}/create]
Creates a new configuration row from an existing row version in [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + row_id (required) - Id of the configuration row
    + version_id (required) - Id of the configuration row version to copy from

+ Attributes
    + targetConfigId (optional, string) - Copy the row to another existing configuration. If not provided, the row will be copied to the original configuration.
    + changeDescription (optional, string) - Version change description

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "targetConfigId": "236606822",
                "changeDescription": "Copy to another row"
            }

+ Response 201 (application/json)

            {
                "id": "236791247",
                "configuration": {
                    "host": "localhost",
                    "port": 4406
                },
                "name": "",
                "description": "",
                "isDisabled": false,
                "version": 1,
                "created": "2017-02-15T00:38:58+0100",
                "creatorToken": {
                    "id": 27978,
                    "description": "ondrej.popelka@keboola.com"
                },
                "changeDescription": "Copy to another row",
                "versionIdentifier": "01H59WQGTDQT8AC7XNWKQDS75P"
            }

### Create Configuration Row copy - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 201 (application/json)

## Create or List Configuration Workspaces [/v2/storage/components/{component_id}/configs/{config_id}/workspaces]

### Create Configuration Workspaces [POST /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/workspaces?async={async}]
Creates a new workspace for an existing configuration in [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration
    + async (optional, boolean) - Create workspace in a background job. Calling the parameter as `async=false` is deprecated.

+ Attributes
    + backend: snowflake (optional, enum[string]) - Workspace backend. When omitted, the default backend is used.
        + Members
            + snowflake
            + bigquery
            + abs - Azure blob storage file workspace
    + backendSize: small (optional, enum[string]) - Workspace backend size. Available only for `snowflake` backend and projects having `workspace-snowflake-dynamic-backend-size` feature enabled.
        + Members
            + small
            + medium
            + large
    + networkPolicy: system (optional, enum[string]) - Network policy applied to workspace user when created.
        + Members
            + system
            + user
    + readOnlyStorageAccess: (optional, boolean) - Allows read only access to all objects in Storage.
    + loginType: (optional, enum[string]) - Request credentials type for new workspace. backend attribute is required when loginType is set.
        + Members
            + default
            + `snowflake-legacy-service` - LEGACY_SERVICE type user is created with password
            + `snowflake-person-sso` - PERSON type user is created without password, login is possible only from Keboola Connection UI
            + `snowflake-person-keypair` - PERSON type user is created with keypair authentication (publicKey required)
            + `snowflake-service-keypair` - SERVICE type user is created with keypair authentication (publicKey required)
    + publicKey: (optional, string) - Public key for user authentication. Required when loginType is set to `snowflake-person-keypair`.
    + useCase: (optional, enum[string]) - Use "reader" to create reader workspace.
        + Members
            + normal
            + reader

+ Request (application/json)
    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "backend": "snowflake"
            }

+ Response 201 (application/json)
    Synchronous call response (async=false)

   + Attributes (WorkspaceCreated)

+ Response 202 (application/json)
    Asynchronous call response (async=true) that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)
    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "workspaceCreate",
                "operationParams": {
                    "values": {
                        "backend": "snowflake"
                        "branchId": 1
                        "component_id": "wr-db"
                        "config_id": "123"
                    },
                },
                "createdTime": "2013-05-31T16:11:05+0200",
                "startTime": null,
                "endTime": null,
                "runId": null,
                "results": null,
                "creatorToken": {
                    "id": "27978",
                    "description": "roman.bracinik@keboola.com"
                },
                "metrics": {
                    "inCompressed": false,
                    "inBytes": 0,
                    "inBytesUncompressed": 0,
                    "outCompressed": false,
                    "outBytes": 0,
                    "outBytesUncompressed": 0
                }
            }

### Workspace List [GET /v2/storage/branch/{branch_id}/components/{component_id}/configs/{config_id}/workspaces]
Returns all workspaces for the component configuration in [Development Branch](#reference/development-branches).

+ Parameters
    + branch_id (required) - Id of the development branch
    + component_id (required) - Id of the component - e.g. `keboola.ex-db-mysql`
    + config_id (required) - Id of the configuration

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

   + Attributes (array[Workspace])

### Create Configuration Workspaces - without branch in URL (deprecated) [POST]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 201 (application/json)

### Workspace List - without branch in URL (deprecated) [GET]

***Deprecated**, use the branch endpoint and set `branch/default`.*

+ Response 200 (application/json)

# Group Scheduled tasks

# Scheduled tasks [/v2/storage/scheduled-tasks]

## Delete task [DELETE /v2/storage/scheduled-tasks/{task_id}]

+ Parameters
    + taks_id (required) - UUID of scheduled task to delete.

+ Request
    + Headers
        X-StorageApi-Token: your_token

+ Response 204

# Group Search
## Search Tables [/v2/storage/search/tables?metadataKey={metadataKey}&metadataValue={metadataValue}&metadataProvider={metadataProvider}&include={include}]

### Search Tables [GET]
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.

+ Parameters
    + include (optional, enum[string]) - Comma separated list of resources to include for each table.
        + Members
            + 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. Works across projects for linked buckets
        + Default: metadata
    + metadataKey (optional, string) - string to search with exact match on one of existing metadata.key
        + Default: NULL
    + metadataValue (optional, string) - string to search with exact match on one of existing metadata.value
        + Default: NULL
    + metadataProvider (optional, string) - string to search with exact match on one of existing metadata.provider
        + Default: NULL
+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "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",
                    "columns": [
                        "time_spent_in_shop",
                        "number_of_items"
                    ],
                    "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",
                        "tables": "https:\/\/connection.keboola.com\/v2\/storage\/buckets\/in.c-application-testing\/tables",
                        "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,
                    },
                    "columnMetadata": {
                        "number_of_items": [
                            {
                                "id": "207947778",
                                "key": "KBC.datatype.basetype",
                                "value": "INTEGER",
                                "provider": "user",
                                "timestamp": "2019-08-14T16:55:34+0200"
                            }
                        ]
                    }
                },
                {
                    "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",
                    "transactional": false,
                    "primaryKey": [],
                    "created": "2016-06-23T20:41:38+0200",
                    "lastImportDate": "2016-07-07T11:26:03+0200",
                    "lastChangeDate": "2016-07-07T11:26:05+0200",
                    "rowsCount": 48,
                    "dataSizeBytes": 12288,
                    "isAlias": true,
                    "isAliasable": true,
                    "timestampType": "MANAGED",
                    "isTyped": false,
                    "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",
                        "isAlias": false,
                        "project": {
                            "id": 578,
                            "name": "Some source project"
                        },
                        "columnMetadata": {
                            "number_of_items": [
                                {
                                    "id": "207947778",
                                    "key": "KBC.datatype.basetype",
                                    "value": "INTEGER",
                                    "provider": "user",
                                    "timestamp": "2019-08-14T16:55:34+0200"
                                }
                            ]
                        }
                    },
                    "aliasColumnsAutoSync": true,
                    "columns": [
                        "time_spent_in_shop",
                        "number_of_items"
                    ],
                    "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",
                        "tables": "https:\/\/connection.keboola.com\/v2\/storage\/buckets\/in.c-application-testing\/tables",
                        "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,
                    },
                    "columnMetadata": []
                }
            ]

## Search Components Configurations [/v2/storage/branch/{branchId}/search/component-configurations?componentId={componentId}&configurationId={configurationId}&metadataKeys={metadataKeys}&include={include}]

### Search Component Configurations [GET]
Search all component configurations accessible by the token by either idComponent, configurationId or metadataKeys. By default, all configurations are returned with their
idComponent and configurationId.

+ Parameters
    + branchId (required) - Id of the development branch

+ Parameters
    + componentId (optional, string) - Id of the Component
        + Default: NULL
    + configurationId (optional, string) - Id of the configuration
        + Default: NULL
    + metadataKeys (optional, array) - metadataKeys (optional, array) - array of metadata keys to search with exact match - e.g. [keyOne, keyTwo] → any configuration that has either key set will be returned
        + Default: NULL
    + include (optional, enum[string]) - Comma separated list of resources to include for each table.
        + Members
            + filteredMetadata

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            [
                {
                    "idComponent": "transformation",
                    "configurationId": "main-1",
                    "metadata": {
                        [
                            "id": "123",
                            "key": "KBC.SomeEnity.metadataKey",
                            "value": "some value",
                            "timestamp": "2021-10-22T10:21:36+0200"
                        ],
                        [
                            "id": "1",
                            "key": "someMetadataKey",
                            "value": "some value",
                            "timestamp": "2021-10-22T10:21:36+0200"
                        ]
                    }
                },
                {
                    "idComponent": "wr-db",
                    "configurationId": "main-2",
                    "metadata": {
                        [
                            "id": "124",
                            "key": "KBC.SomeEnity.metadataKey",
                            "value": "other value",
                            "timestamp": "2021-10-22T10:21:36+0200"
                        ]
                    }
                }
            ]

## Global search [/v2/storage/global-search?query={query}&limit={limit}&offset={offset}&types={types}&projectIds={projectIds}&branchTypes={branchTypes}&branchIds={branchIds}]

### Global search [GET]
Search across names of configuration rows, configurations, tables and buckets.

+ Parameters
    + query (required, string) - search query
    + limit (optional, integer) - Limit number of results
    + offset (optional, integer) - Pagination offset of results
    + types (optional, array) - Search in specific type: flow, bucket, table, transformation, configuration, configuration-row, workspace and shared-code.
    + projectIds (optional, array) - Array of integers of projects where search performs
    + branchTypes (optional, string) - Branch type where to search. Possible options: production, development
    + branchIds (optional, array) - Array of integers of branches where search performs

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)
    + Body

            {
                "all": 1,
                "items": [
                    {
                        "id": 1,
                        "type": "configuration",
                        "name": "Configuration Name",
                        "fullPath": {
                            "project": {
                                "id": 10,
                                "name": "Project name"
                            },
                            "branch": {
                                "id": 20,
                                "name": "Branch name",
                                "isDefault": true,
                                "isNative": true
                            },
                            "component": {
                                "id": "component-id",
                                "name": "Component name"
                            }
                        },
                        "componentId": "component-id",
                        "organizationId": 30,
                        "projectId": 10,
                        "created": "2024-06-20T10:50:40:30+02:00"
                    },
                ],
                "byType": {
                    "total": 1,
                    "configuration": 1
                },
                "byProject": {
                    "10": "Project name"
                },
            }

# Group Stats
## RunId [/v2/storage/stats?runId={runId}]
### Stats detail [GET]
Gets stats for a given Run Id. Provides the count of imported/exported tables and files in a specified run with durations.

+ Request
    + Headers

            X-StorageApi-Token: your_token

+ Response 200

            {
                "tables": {
                    "import": {
                        "other": 0,
                        "tables": [
                            {
                                "id": "out.c-futurelytics.order_lines",
                                "count": 1,
                                "durationTotalSecs": 103.53275680542
                            }
                        ]
                    },
                    "export": {
                        "other": 0,
                        "tables": []
                    }
                },
                "files": {
                    "total": {
                        "count": 5,
                        "dataSizeBytes": {
                            "total": 4916667019,
                            "mean": 983333403.8,
                            "max": 4552728847,
                            "min": 51
                        }
                    },
                    "tags": {
                        "other": 0,
                        "tags": []
                    }
                }
            }
# Group Triggers

### Create [POST /v2/storage/triggers/]
Created a trigger listening on set of tables

Token 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.
When updating the component of trigger you need permissions for both the current component and the component you're updating the trigger to.

+ Attributes
    + runWithTokenId (required, number) - ID of token used for running configured component
    + component: `orchestration` (required, enum[string]) - For now we support only 'orchestration'
    + configurationId (required, string) - Id of component configuration
    + coolDownPeriodMinutes (required, number) - Minimal cool down period before firing action again in minutes (min is 1 minute)
    + tabledIds (required, object) - Array of tables ids
        + tableId (string) - Id of table (like "in.c-test.watched")
+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "runWithTokenId": 123,
                "component": "orchestration",
                "configurationId": "123",
                "coolDownPeriodMinutes": 20,
                "tableIds": [
                    "in.c-test.watched-1",
                    "in.c-prod.watched-5"
                ]
            }

+ Response 201 (application/json)

        {
            "id": "3",
            "runWithTokenId": 123,
            "component": "orchestration",
            "configurationId": "config-100",
            "lastRun": "2017-02-13T16:42:00+0100",
            "coolDownPeriodMinutes": 20,
            "creatorToken": {
                "id": 1,
                "description": "dev@keboola.com"
            },
            "tables": [
                {
                    "tableId": "in.c-test.watched-1"
                },
                {
                    "tableId": "in.c-prod.watched-5"
                }
            ]
        }

### List [GET /v2/storage/triggers/?component={component}&configurationId={configurationId}]
List all token of project with possible filters

+ Parameters
    + component (optional, string) - type of component. Now we supports only 'orchestration'
    + configurationId (optional, string) - id of component configuration

+ Response 200 (application/json)

        [
            {
                "id": "3",
                "runWithTokenId": 123,
                "component": "orchestration",
                "configurationId": "config-100",
                "lastRun": "2017-02-13T16:42:00+0100",
                "coolDownPeriodMinutes": 20,
                "creatorToken": {
                    "id": 1,
                    "description": "dev@keboola.com"
                },
                "tables": [
                    {
                        "tableId": "in.c-test.watched-1"
                    },
                    {
                        "tableId": "in.c-prod.watched-5"
                    }
                ]
            }
        ]

## Get, update or delete [/v2/storage/triggers/{id}]

### Get detail [GET]
Get trigger detail

+ Parameters
    + id (required, number) - ID of trigger you want to get

+ Request

    + Headers

            X-StorageApi-Token: your_token

+ Response 200 (application/json)

        {
            "id": "3",
            "runWithTokenId": 123,
            "component": "orchestration",
            "configurationId": "config-100",
            "lastRun": "2017-02-13T16:42:00+0100",
            "coolDownPeriodMinutes": 20,
            "creatorToken": {
                "id": 1,
                "description": "dev@keboola.com"
            },
            "tables": [
                {
                    "tableId": "in.c-test.watched-1"
                },
                {
                    "tableId": "in.c-prod.watched-5"
                }
            ]
        }

### Update [PUT]
Updates an existing trigger

+ Parameters
    + id (required, number) - ID of trigger you want to update

+ Attributes
    + runWithTokenId (optional, number) - Id of token used for running configured component
    + component `orchestration` (optional, enum[string]) - For now we support only 'orchestrations'
    + configurationId (optional, string) - Id of component configuration
    + coolDownPeriodMinutes (optional, number) - Minimal cool down period before firing action again in minutes (min is 1 minute)
    + tabledIds (optional, object) - Array of tables ids
        + tableId (string) - Id of table (like "in.c-test.watched")

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "runWithTokenId": 100
            }

+ Response 200 (application/json)

        {
            "id": "3",
            "runWithTokenId": 123,
            "component": "orchestration",
            "configurationId": "config-100",
            "lastRun": "2017-02-13T16:42:00+0100",
            "coolDownPeriodMinutes": 20,
            "creatorToken": {
                "id": 1,
                "description": "dev@keboola.com"
            },
            "tables": [
                {
                    "tableId": "in.c-test.watched-1"
                },
                {
                    "tableId": "in.c-prod.watched-5"
                }
            ]
        }

### Delete [DELETE]
Deletes an existing trigger.

+ Parameters

    + id (required, number) - ID of trigger you want to delete

+ Request

    + Headers

            X-StorageApi-Token: your_token

+ Response 204

# Group Webalize

### Webalize Display Name [POST /v2/storage/webalize/display-name]
Webalize string which you want to use as `displayName` for [tables](https://keboola.docs.apiary.io/#reference/tables/manage-tables/table-update)
and [buckets](https://keboola.docs.apiary.io/#reference/buckets/manage-bucket/bucket-update)
+ Attributes
    + displayName (required, string)

+ Request (application/json)

    + Body

            {
                "displayName": "My$$Display-Name"
            }

+ Response 200 (application/json)

        {
            "displayName": "My-Display-Name"
        }

### Webalize Column Names [POST /v2/storage/webalize/column-names]
Webalize strings. Do not validate if you can use them in database column names.

+ Attributes
    + columnNames (required, array[string])

+ Request (application/json)

    + Body

            {
                "columnNames": [
                    "First$$Column-Name",
                    "Second Column-Name"
                ]
            }

+ Response 200 (application/json)

        {
            "columnNames": [
                "My_Column_Name",
                "Second_Column_Name"
            ]
        }

# Group Validate

### Validate column names [POST /v2/storage/validate/column-names]
Validate strings if they can be used as column names. Column names can be used for example:
- [creating a table](https://keboola.docs.apiary.io/#reference/tables/create-table-definition/create-new-table-definition)
- [adding a column](https://keboola.docs.apiary.io/#reference/tables/create-table-column/add-column-to-table)

+ Attributes
    + columnNames (required, array[string])

+ Request (application/json)

    + Body

            {
                "columnNames": [
                    "First$$Column-Name",
                    "Second Column-Name"
                ]
            }

+ Response 204
If all columns are valid

+ Response 422

    + Body

        {
            [
                ""First$$Column-Name" contains not allowed characters. Only alphanumeric characters dash and underscores are allowed.",
                ""Second Column-Name" contains not allowed characters. Only alphanumeric characters dash and underscores are allowed."
            ]
        }

# Group Development Branches

**EXPERIMENTAL**

Development branches allow you to prepare changes to configuration and tables in isolation. When ready, you can replace the production with the development branch.

You can use development branch in selected API calls by changing url.
For example, you want to list configurations ([common](#reference/components-and-configurations/component-configurations/list-configurations) or [development branch](#reference/components-and-configurations/component-configurations/list-development-branch-configurations) version):
- `GET /v2/storage/components/ex-foo/configs` - in default branch (common usage)
- `GET /v2/storage/branch/default/components/ex-foo/configs` - in default branch (with `default` as branch prefix) - same result as above
- `GET /v2/storage/branch/123/components/ex-foo/configs` - in development branch (with `ID` as branch prefix)

## Branches [/v2/storage/dev-branches/]

### List branches [GET]

+ Request

    + Headers

            X-StorageApi-Token: your_token

+ Response 200

    + Body

            [
                {
                    "id": 123,
                    "name": "My branch",
                    "description": "",
                    "created": "2020-09-17T12:17:32+0200",
                    "isDefault": false,
                    "creatorToken": {
                        "id": 267,
                        "name": "dev@keboola.com"
                    }
                },
                {
                    "id": 124,
                    "name": "My second branch",
                    "description": "",
                    "created": "2020-09-17T10:03:16+0200",
                    "isDefault": false,
                    "creatorToken": {
                        "id": 267,
                        "name": "dev@keboola.com"
                    }
                },
                {
                    "id": 5,
                    "name": "Main",
                    "description": "",
                    "created": "2020-09-22T13:05:04+0200",
                    "isDefault": true,
                    "creatorToken": []
                }
            ]

### Create branch [POST]

+ Attributes
    + name (required, string) - name of the branch
    + description (optional, string) - description of the branch

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "name": "Refactor DB extractors"
            }

+ Response 202

    + Body

            {
                "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"
                    }
                },
                "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
                }
            }

## Branch manipulation [/v2/storage/dev-branches/{id}]

### Branch detail [GET]

+ Parameters
    + id (required, number) - id of the branch

+ Request

    + Headers

            X-StorageApi-Token: your_token

+ Response 200

    + Body

            {
                "id": 123,
                "name": "My branch",
                "description": "",
                "created": "2020-09-17T12:17:32+0200",
                "isDefault": false,
                "creatorToken": {
                    "id": 267,
                    "name": "dev@keboola.com"
                }
            }

### Branch update [PUT]

Update of a default branch name is not allowed.

+ Parameters
    + id (required, number) - id of the branch

+ Attributes
    + name (optional, string) - new name
    + description (optional, string) - new description

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token
    + Body

            {
                "description": "Some description"
            }

+ Response 200

    + Body

            {
                "id": 123,
                "name": "My branch",
                "description": "Some description",
                "created": "2020-09-17T12:17:32+0200",
                "isDefault": false,
                "creatorToken": {
                    "id": 267,
                    "name": "dev@keboola.com"
                }
            }

### Delete branch [DELETE]

Deletes a development branch with all buckets(tables) belong to the development branch,
other buckets (production buckets or buckets belongs the other development branch) will be preserved.
+ Parameters
    + id (required, number) - id of the branch

+ Request

    + Headers

            X-StorageApi-Token: your_token

+ Response 202

    + Body

            {
                "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-05T18:58:11+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
                }
            }

## Merge requests [/v2/storage/merge-request/]

### Create merge request [POST]

+ Attributes
    + branchFromId (required, number) - ID of the branch to merge
    + branchIntoId (required, number) - ID of the branch to merge into (default branch)
    + title (required, string) - title of the merge request
    + description (optional, string) - description of the merge request
    + externalId (optional, string) - identifier of the merge request in an external system
    + autoMergeStrategy (optional, enum[string]) - auto-merge strategy
        + Members
            + `immediately`
            + `scheduled`
            + `none`
    + autoMergeAt (optional, string) - ISO 8601 datetime for scheduled auto-merge, required when autoMergeStrategy is "scheduled" (e.g. "2026-04-01T12:00:00+00:00")
    + reviewerIds (optional, array[number]) - list of user IDs to assign as reviewers

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "branchFromId": 124
                "branchIntoId": 123,
                "title": "Refactor DB extractors",
                "description": "DB exctractor have new columns now",
                "externalId": "ticket-123",
                "autoMergeStrategy": "scheduled",
                "autoMergeAt": "2026-04-01T12:00:00+00:00"
            }

+ Response 201 (application/json)

    + Body

            {
            "id": 11,
            "creator": {
                  "id": 7,
                  "name": "John Doe"
            },
            "title": "Refactor DB extractors",
            "description": "DB exctractor have new columns now",
            "state": "development",
            "branches": {
                  "branchFromId": 124,
                  "branchIntoId": 123
            },
            "merge": {
                  "mergedAt": null,
                  "mergerId": null,
                  "mergerName": ""
            },
            "externalId": "ticket-123",
            "autoMergeStrategy": "scheduled",
            "autoMergeAt": "2026-04-01T12:00:00+00:00",
            "approvals": [
            {
                  "approverId": 123,
                  "approverName": "John Doe",
                  "createdAt": "2023-06-16T10:20:58+0200"
            }
            ],
            "createdAt": "2023-06-15T10:20:58+0200"
            }


### List Merge requests [GET /v2/storage/merge-request]
List all merge requests available in the project defined by token.

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token


+ Response 200 (application/json)

    + Body
            [
                {
                "id": 11,
                "creator": {
                      "id": 7,
                      "name": "John Doe"
                },
                "title": "Refactor DB extractors",
                "description": "DB exctractor have new columns now",
                "state": "in_review",
                "branches": {
                      "branchFromId": 124,
                      "branchIntoId": 123
                },
                "merge": {
                      "mergedAt": null,
                      "mergerId": null,
                      "mergerName": ""
                },
                "externalId": "ticket-123",
                "autoMergeStrategy": "scheduled",
                "autoMergeAt": "2026-04-01T12:00:00+00:00",
                "approvals": [
                {
                      "approverId": 123,
                      "approverName": "John Doe",
                      "createdAt": "2023-06-16T10:20:58+0200"
                }
                ],
                "createdAt": "2023-06-15T10:20:58+0200"
                }
            ]


## Merge request [/v2/storage/merge-request/{id}]

### Merge request detail [GET]

Detail of Merge request also contains `content` of changed objects.
+ Parameters
    + id (required, number) - merge request ID

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token


+ Response 200 (application/json)

    + Body

            {
            "id": 11,
            "creator": {
                  "id": 7,
                  "name": "John Doe"
            },
            "title": "Refactor DB extractors",
            "description": "DB exctractor have new columns now",
            "state": "in_review",
            "changeLog": {
                "configurations": [
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-1",
                        "lastVersionIdentifier": "01H5M1BDJHD1K6N3G14EZ8XDE2"
                    },
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-2",
                        "lastVersionIdentifier": "01H5M1B47BX3W4GM4CDH40J330"
                    }
                ]
            },
            "branches": {
                  "branchFromId": 124,
                  "branchIntoId": 123
            },
            "merge": {
                  "mergedAt": null,
                  "mergerId": null,
                  "mergerName": ""
            },
            "externalId": "ticket-123",
            "autoMergeStrategy": "scheduled",
            "autoMergeAt": "2026-04-01T12:00:00+00:00",
            "approvals": [
            {
                  "approverId": 123,
                  "approverName": "John Doe",
                  "createdAt": "2023-06-16T10:20:58+0200"
            }
            ],
            "createdAt": "2023-06-15T10:20:58+0200"
            }

### Update merge request [PUT]

+ Parameters
    + id (required, number) - merge request ID

+ Attributes
    + title (optional, string) - title of the merge request; omit to keep unchanged, empty string is not allowed
    + description (optional, string) - description of the merge request; omit to keep unchanged, send empty string to clear
    + externalId (optional, string) - identifier of the merge request in an external system; omit to keep unchanged, send empty string to clear
    + autoMergeStrategy (optional, enum[string]) - auto-merge strategy; omit to keep unchanged, send "none" to disable
        + Members
            + `immediately`
            + `scheduled`
            + `none`
    + autoMergeAt (optional, string) - ISO 8601 datetime for scheduled auto-merge, required when autoMergeStrategy is "scheduled" (e.g. "2026-04-01T12:00:00+00:00")
    + reviewerIds (optional, array[number]) - list of user IDs to assign as reviewers; omit to keep unchanged, send empty array to clear

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token

    + Body

            {
                "title": "New title",
                "description": "New desc",
                "externalId": "ticket-123",
                "autoMergeStrategy": "immediately"
            }

+ Response 200 (application/json)

    + Body

            {
            "id": 11,
            "creator": {
                  "id": 7,
                  "name": "John Doe"
            },
            "title": "New title",
            "description": "New desc",
            "state": "development",
            "branches": {
                  "branchFromId": 124,
                  "branchIntoId": 123
            },
            "merge": {
                  "mergedAt": null,
                  "mergerId": null,
                  "mergerName": ""
            },
            "externalId": "ticket-123",
            "autoMergeStrategy": "immediately",
            "autoMergeAt": null,
            "approvals": [
            {
                  "approverId": 123,
                  "approverName": "John Doe",
                  "createdAt": "2023-06-16T10:20:58+0200"
            }
            ],
            "createdAt": "2023-06-15T10:20:58+0200"
            }

## Put MR in review [/v2/storage/merge-request/{id}/request-review]

### Put MR in review [PUT]
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.
+ Parameters
    + id (required, number) - merge request ID

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token


+ Response 200 (application/json)

    + Body

            {
            "id": 11,
            "creator": {
                  "id": 7,
                  "name": "John Doe"
            },
            "title": "Refactor DB extractors",
            "description": "DB exctractor have new columns now",
            "state": "in_review",
            "changeLog": {
                "configurations": [
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-1",
                        "lastVersionIdentifier": "01H5M1BDJHD1K6N3G14EZ8XDE2"
                    },
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-2",
                        "lastVersionIdentifier": "01H5M1B47BX3W4GM4CDH40J330"
                    }
                ]
            }
            "branches": {
                  "branchFromId": 124,
                  "branchIntoId": 123
            },
            "merge": {
                  "mergedAt": null,
                  "mergerId": null,
                  "mergerName": ""
            },
            "externalId": "ticket-123",
            "autoMergeStrategy": "scheduled",
            "autoMergeAt": "2026-04-01T12:00:00+00:00",
            "approvals": [
            {
                  "approverId": 123,
                  "approverName": "John Doe",
                  "createdAt": "2023-06-16T10:20:58+0200"
            }
            ],
            "createdAt": "2023-06-15T10:20:58+0200"
            }

## Approve [/v2/storage/merge-request/{id}/approve]

### Approve [PUT]

Each project has defined required number of approvals. If the last approval arrives, MR changes it state to `approved`.
+ Parameters
    + id (required, number) - merge request ID

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token


+ Response 200 (application/json)

    + Body

            {
            "id": 11,
            "creator": {
                  "id": 7,
                  "name": "John Doe"
            },
            "title": "Refactor DB extractors",
            "description": "DB exctractor have new columns now",
            "state": "in_review",
            "changeLog": {
                "configurations": [
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-1",
                        "lastVersionIdentifier": "01H5M1BDJHD1K6N3G14EZ8XDE2"
                    },
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-2",
                        "lastVersionIdentifier": "01H5M1B47BX3W4GM4CDH40J330"
                    }
                ]
            },
            "branches": {
                  "branchFromId": 124,
                  "branchIntoId": 123
            },
            "merge": {
                  "mergedAt": null,
                  "mergerId": null,
                  "mergerName": ""
            },
            "externalId": "ticket-123",
            "autoMergeStrategy": "scheduled",
            "autoMergeAt": "2026-04-01T12:00:00+00:00",
            "approvals": [
            {
                  "approverId": 123,
                  "approverName": "John Doe",
                  "createdAt": "2023-06-16T10:20:58+0200"
            }
            ],
            "createdAt": "2023-06-15T10:20:58+0200"
            }

## Merge MR [/v2/storage/merge-request/{id}/merge]

### Merge MR [PUT]
Apply changes in MR and all changes in configurations are moved to the production (default) branch. Returns a job that tracks the merge progress.
+ Parameters
    + id (required, number) - merge request ID

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token


+ Response 202
Asynchronous call response that creates a new job. To see job detail use [Job Detail API endpoint](#reference/jobs/manage-jobs/job-detail)

    + Body

            {
                "id": 11,
                "status": "waiting",
                "url": "https://connection.keboola.com/v2/storage/jobs/11",
                "operationName": "mergeRequestMerge",
                "operationParams": {
                    "id": 11
                },
                "createdTime": "2023-06-26T10:20:58+0200"
            }


## Request merge request changes [/v2/storage/merge-request/{id}/request-changes]

### Request merge request changes [PUT]

Requesting changes will remove all approvals and move the Merge request to `development` state.

+ Parameters
    + id (required, number) - merge request ID

+ Request (application/json)

    + Headers

            X-StorageApi-Token: your_token


+ Response 200 (application/json)

    + Body

            {
            "id": 11,
            "creator": {
                  "id": 7,
                  "name": "John Doe"
            },
            "title": "Refactor DB extractors",
            "description": "DB exctractor have new columns now",
            "state": "in_review",
            "changeLog": {
                "configurations": [
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-1",
                        "lastVersionIdentifier": "01H5M1BDJHD1K6N3G14EZ8XDE2"
                    },
                    {
                        "isDeleted": false,
                        "componentId": "wr-db",
                        "configurationId": "main-2",
                        "lastVersionIdentifier": "01H5M1B47BX3W4GM4CDH40J330"
                    }
                ]
            },
            "branches": {
                  "branchFromId": 124,
                  "branchIntoId": 123
            },
            "merge": {
                  "mergedAt": null,
                  "mergerId": null,
                  "mergerName": ""
            },
            "externalId": "ticket-123",
            "autoMergeStrategy": "scheduled",
            "autoMergeAt": "2026-04-01T12:00:00+00:00",
            "approvals": [
            {
                  "approverId": 123,
                  "approverName": "John Doe",
                  "createdAt": "2023-06-16T10:20:58+0200"
            }
            ],
            "createdAt": "2023-06-15T10:20:58+0200"
            }

## Data Structures

### OrderByObject (object)
+ column (required): name of column used for sorting
+ order (optional, enum[string])
    + Members
        + ASC - ascending sort
        + DESC - descending sort
    + Default: ASC
+ dataType (optional, enum[string]) - required when sorting by column contains numeric value, disallowed for tables with native types
    + Members
        + INTEGER - for numbers without a decimal point (Snowflake, BigQuery)
        + DOUBLE - for number with a decimal point (Snowflake, BigQuery)
        + BIGINT - for number without a decimal point (BigQuery)
        + REAL - for number with a decimal point (BigQuery)
        + DECIMAL - for numbers (BigQuery)


### WhereFiltersObject (object)
+ column (required) - column which should be matched
+ operator (required, enum[string]) - operator for value comparision
    + Members
        + eq - Equals - can be used with multiple values
        + ne - Not equals  - case be used with multiple values
        + gt - Greater than - Snowflake only
        + ge - Greater than or equals - Snowflake only
        + lt - Less than - Snowflake only
        + le - Less than or equals  - Snowflake only
    + Default: eq
+ values (required, array[string]) - array of variables to compare
+ dataType (optional, enum[string]) - For comparing (`[gt|lt|le|ge]`) numeric values you have to specify data type. BigQuery supports all listed types and converts them to BigQuery equivalent in the background
    + Members
        + INTEGER - for numbers without a decimal point (Snowflake, BigQuery)
        + DOUBLE - for number with a decimal point (Snowflake, BigQuery)
        + BIGINT - for number without a decimal point (BigQuery)
        + REAL - for number with a decimal point (BigQuery)
        + DECIMAL - for numbers (BigQuery)
+ type (optional, enum[string]) - type of filter values interpretation
    + Members
        + SCALAR - default value type interpretation (default)
        + TIME_STRING - values are interpreted as date/time strings and converted to timestamps. When using TIME_STRING, dataType must be empty. Values must be valid date/time strings compatible with strtotime() or unix timestamps. All time strings are converted to UTC timezone. Be aware of your backend timezone settings and daylight saving time changes.
    + Default: SCALAR


### CreateTableDefinitionAsyncBase

+ name (required) - New table name
+ delimiter (optional) - Field delimiter used in the CSV file. The default value is ','.  Use '\t' or type the tab char for the tabulator.
+ enclosure (optional) - Field enclosure used in the CSV file. The default value is '"'. (Note: you can specify either the `enclosure` or `escapedBy` parameter, not both.)
+ escapedBy (optional) - Escape character used in the CSV file. The default value is an empty value - no escape character is used. (Note: you can specify either the `enclosure` or `escapedBy` parameter, not both.)
+ primaryKey (optional) - Primary key of a table. If the primary key is set, updates can be done on the table. See CSV incremental import. The primary key can be also composed by multiple columns; the columns must be separated by a comma.
+ timestampType (optional, enum[string]) - Type of internal timestamp column only MANAGED value now supported, meaning that _timestamp column managed by storage is created.
        + Members
            + MANAGED
        + Default: MANAGED

### CreateTableDefinitionAsyncFile(CreateTableDefinitionAsyncBase)

+ dataFileId (required, number) - Id of the file stored in [File Uploads](#reference/files)

### CreateTableDefinitionAsyncWorkspace(CreateTableDefinitionAsyncBase)

+ dataWorkspaceId (required, number) - Load from the table [workspace](#reference/workspaces). Use with the **dataObject** attribute.
+ dataTableName (optional, string) - (deprecated - use dataObject) ~~Load from the table in the [workspace](#reference/workspaces).~~
+ dataObject (optional, string) - Load from the table/file in the [workspace](#reference/workspaces).

### CreateTableDefinitionAsyncSnapshot(CreateTableDefinitionAsyncBase)

+ snapshotId (required, number) - Id of a table snapshot - a table will be created from the snapshot.

### CreateTableDefinitionAsyncTimeTravel(CreateTableDefinitionAsyncBase)

+ sourceTableId (required, string) - Create time travel snapshot of this table.
+ timestamp (required) - Datetime string. The preferred format is `YYYY-MM-DD hh:mm:ss Z`, other formats may also work, but time zone is required.

### GCPCredentials
+ type: service_account (string, required)
+ project_id: 123456789 (string, required)
+ private_key_id: xxx (string, required)
+ private_key: `-----BEGIN PRIVATE KEY-----<key contents>-----END PRIVATE KEY-----\n` (string, required)
+ client_email: something@else.iam.gserviceaccount.com (string, required)
+ client_id: 123456789 (string, required)
+ auth_uri: https://accounts.google.com/o/oauth2/auth (string, required)
+ token_uri: https://oauth2.googleapis.com/token (string, required)
+ auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs (string, required)
+ client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/something (string, required)