API docs by Redocly

OpenAPI spec for ClickHouse Cloud (1.0)

Download OpenAPI specification:Download

ClickHouse Support: [email protected] URL: https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-103952

Get list of available organizations

Returns a list with a single organization associated with the API key in the request.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

Get organization details

Returns details of a single organization. In order to get the details, the auth key must belong to the organization.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Update organization details

Updates organization fields. Requires ADMIN auth key role.

path Parameters
Organization ID
required
string <uuid>

ID of the organization to update.

Request Body schema: application/json
name
string

Name of the organization.

object (OrganizationPrivateEndpointsPatch)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "privateEndpoints": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

List of organization services

Returns a list of all services in the organization.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

Create new service

Creates a new service in the organization, and returns the current service state and a password to access the service. The service is started asynchronously.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that will own the service.

Request Body schema: application/json
name
string

Name of the service. Alphanumerical string with whitespaces up to 50 characters.

provider
string
Enum: "aws" "gcp" "azure"

Cloud provider

region
string
Enum: "ap-south-1" "ap-southeast-1" "eu-central-1" "eu-west-1" "eu-west-2" "us-east-1" "us-east-2" "us-west-2" "ap-southeast-2" "ap-northeast-1" "us-east1" "us-central1" "europe-west4" "asia-southeast1" "eastus" "eastus2" "westus3" "germanywestcentral"

Service region.

tier
string
Enum: "development" "production" "dedicated_high_mem" "dedicated_high_cpu" "dedicated_standard"

Tier of the service: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard'. Production services scale, Development are fixed size.

Array of objects (IpAccessListEntry)

List of IP addresses allowed to access the service

minTotalMemoryGb
number multiple of 12 [ 24 .. 720 ]

Minimum total memory of all workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and greater than 24.

maxTotalMemoryGb
number multiple of 12 [ 24 .. 720 ]

Maximum total memory of all workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and lower than 360 for non paid services or 720 for paid services.

numReplicas
number [ 3 .. 25 ]

Number of replicas for the service. Must be greater than 3 and less than 25. Contact support to enable this feature.

idleScaling
boolean

When set to true the service is allowed to scale down to zero when idle. Always true for development services.

idleTimeoutMinutes
number

Set minimum idling timeout (in minutes). Must be >= 5 minutes.

backupId
string <uuid>

Optional backup ID used as an initial state for the new service. When used the region and the tier of the new instance must be the same as the values of the original instance.

encryptionKey
string

Optional customer provided disk encryption key

encryptionAssumedRoleIdentifier
string

Optional role to use for disk encryption

privateEndpointIds
Array of strings

List of private endpoints

privatePreviewTermsChecked
boolean

Accept the private preview terms and conditions. It is only needed when creating the first service in the organization in case of a private preview

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "provider": "aws",
  • "region": "ap-south-1",
  • "tier": "development",
  • "ipAccessList": [
    ],
  • "minTotalMemoryGb": 48,
  • "maxTotalMemoryGb": 360,
  • "numReplicas": 3,
  • "idleScaling": true,
  • "idleTimeoutMinutes": 0,
  • "backupId": "eb7cea43-10b2-42dd-8819-ab9aed37565f",
  • "encryptionKey": "string",
  • "encryptionAssumedRoleIdentifier": "string",
  • "privateEndpointIds": [
    ],
  • "privatePreviewTermsChecked": true
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Get service details

Returns a service that belongs to the organization

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the service.

Service ID
required
string <uuid>

ID of the requested service.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Update service basic details.

Updates basic service details like service name or IP access list.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the service.

Service ID
required
string <uuid>

ID of the service to update.

Request Body schema: application/json
name
string

Name of the service. Alphanumerical string with whitespaces up to 50 characters.

object (IpAccessListPatch)
object (InstancePrivateEndpointsPatch)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "ipAccessList": {
    },
  • "privateEndpointIds": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Delete service.

Deletes the service. The service must be in stopped state and is deleted asynchronously after this method call.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the service.

Service ID
required
string <uuid>

ID of the service to delete.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

Get private endpoint configuration

Information required to set up a private endpoint

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Service ID
required
string <uuid>

ID of the requested service.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Update service state.

Starts or stop service

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the service.

Service ID
required
string <uuid>

ID of the service to update state.

Request Body schema: application/json
command
string
Enum: "start" "stop"

Command to change the state: 'start', 'stop'.

Responses

Request samples

Content type
application/json
{
  • "command": "start"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Update service auto scaling settings.

Updates minimum and maximum total memory limits and idle mode scaling behavior for the service. The memory settings are available only for "production" services and must be a multiple of 12 starting from 24GB. Please contact support to enable adjustment of numReplicas.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the service.

Service ID
required
string <uuid>

ID of the service to update scaling parameters.

Request Body schema: application/json
minTotalMemoryGb
number multiple of 12 [ 24 .. 720 ]

Minimum total memory of all workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and greater than 24.

maxTotalMemoryGb
number multiple of 12 [ 24 .. 720 ]

Maximum total memory of all workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and lower than 360 for non paid services or 720 for paid services.

numReplicas
number [ 3 .. 25 ]

Number of replicas for the service. Must be greater than 3 and less than 25. Contact support to enable this feature.

idleScaling
boolean

When set to true the service is allowed to scale down to zero when idle. Always true for development services.

idleTimeoutMinutes
number

Set minimum idling timeout (in minutes). Must be >= 5 minutes.

Responses

Request samples

Content type
application/json
{
  • "minTotalMemoryGb": 48,
  • "maxTotalMemoryGb": 360,
  • "numReplicas": 3,
  • "idleScaling": true,
  • "idleTimeoutMinutes": 0
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Update service password.

Sets a new password for the service

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the service.

Service ID
required
string <uuid>

ID of the service to update password.

Request Body schema: application/json
newPasswordHash
string

Optional password hash. Used to avoid password transmission over network. If not provided a new password is generated and is provided in the response. Otherwise this hash is used. Algorithm: echo -n "yourpassword" | sha256sum | tr -d '-' | xxd -r -p | base64

newDoubleSha1Hash
string

Optional double SHA1 password hash for MySQL protocol. If newPasswordHash is not provided this key will be ignored and the generated password will be used. To enable this field please contact support as it is experimental. Algorithm: echo -n "yourpassword" | sha1sum | tr -d '-' | xxd -r -p | sha1sum | tr -d '-'

Responses

Request samples

Content type
application/json
{
  • "newPasswordHash": "string",
  • "newDoubleSha1Hash": "string"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

List of service backups

Returns a list of all backups for the service. The most recent backups comes first in the list.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the backup.

Service ID
required
string <uuid>

ID of the service the backup was created from.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

Get backup details

Returns a single backup info.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the backup.

Service ID
required
string <uuid>

ID of the service the backup was created from.

Service backup ID
required
string <uuid>

ID of the requested backup.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Get list of all keys

Returns a list of all keys in the organization.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

Create key

Creates new API key.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that will own the key.

Request Body schema: application/json
name
string

Name of the key.

expireAt
string <date-time>

Timestamp the key expires. If not present or is empty the key never expires. ISO-8601.

state
string
Enum: "enabled" "disabled"

Initial state of the key: 'enabled', 'disabled'. If not provided the new key will be 'enabled'.

object (ApiKeyHashData)
roles
Array of strings
Items Enum: "admin" "developer"

List of roles assigned to the key. Contains at least 1 element.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "expireAt": "2019-08-24T14:15:22Z",
  • "state": "enabled",
  • "hashData": {
    },
  • "roles": [
    ]
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Get key details

Returns a single key details.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

API key ID
required
string <uuid>

ID of the requested key.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Update key

Updates API key properties.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the key.

API key ID
required
string <uuid>

ID of the key to update.

Request Body schema: application/json
name
string

Name of the key

roles
Array of strings
Items Enum: "admin" "developer"

List of roles assigned to the key. Contains at least 1 element.

expireAt
string <date-time>

Timestamp the key expires. If not present or is empty the key never expires. ISO-8601.

state
string
Enum: "enabled" "disabled"

State of the key: 'enabled', 'disabled'.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "roles": [
    ],
  • "expireAt": "2019-08-24T14:15:22Z",
  • "state": "enabled"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Delete key

Deletes API key. Only a key not used to authenticate the active request can be deleted.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that owns the key.

API key ID
required
string <uuid>

ID of the key to delete.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

List organization members

Returns a list of all members in the organization.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

Get member details

Returns a single organization member details.

path Parameters
Organization ID
required
string <uuid>

ID of the organization the member is part of.

User ID
required
string <uuid>

ID of the requested user.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Update organization member.

Updates organization member role.

path Parameters
Organization ID
required
string <uuid>

ID of the organization the member is part of.

User ID
required
string <uuid>

ID of the user to patch

Request Body schema: application/json
role
string
Enum: "admin" "developer"

Role of the member in the organization.

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Remove an organization member

Removes a user from the organization

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

User ID
required
string <uuid>

ID of the requested user.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

List all invitations

Returns list of all organization invitations.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

Create an invitation

Creates organization invitation.

path Parameters
Organization ID
required
string <uuid>

ID of the organization to invite a user to.

Request Body schema: application/json
email
string <email>

Email of the invited user. Only a user with this email can join using the invitation. The email is stored in a lowercase form.

role
string
Enum: "admin" "developer"

Role of the member in the organization.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Get invitation details

Returns details for a single organization invitation.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Organization invitation ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Delete organization invitation

Deletes a single organization invitation.

path Parameters
Organization ID
required
string <uuid>

ID of the organization that has the invitation.

Organization invitation ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6"
}

List of organization activities

Returns a list of all organization activities.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": [
    ]
}

Organization activity

Returns a single organization activity by ID.

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

Activity ID
required
string

ID of the requested activity.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}

Get private endpoint configuration for region within cloud provider for an organization

Information required to set up a private endpoint

path Parameters
Organization ID
required
string <uuid>

ID of the requested organization.

query Parameters
Cloud provider identifier
required
string

Cloud provider identifier. One of aws, gcp, or azure.

Cloud provider region
required
string

Region identifier within specific cloud providers.

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "requestId": "d385ab22-0f51-4b97-9ecd-b8ff3fd4fcb6",
  • "result": {
    }
}