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-136382

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

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
organizationId
required
string <uuid>

ID of the requested organization.

Responses

Response samples

Content type
application/json
{
  • "status": 400,
  • "error": "string"
}

List of organization services

Returns a list of all services in the organization.

path Parameters
organizationId
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
organizationId
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" "dedicated_standard_n2d_standard_4" "dedicated_standard_n2d_standard_8" "dedicated_standard_n2d_standard_32" "dedicated_standard_n2d_standard_128" "dedicated_standard_n2d_standard_32_16SSD" "dedicated_standard_n2d_standard_64_24SSD"

Tier of the service: 'development', 'production', 'dedicated_high_mem', 'dedicated_high_cpu', 'dedicated_standard', 'dedicated_standard_n2d_standard_4', 'dedicated_standard_n2d_standard_8', 'dedicated_standard_n2d_standard_32', 'dedicated_standard_n2d_standard_128', 'dedicated_standard_n2d_standard_32_16SSD', 'dedicated_standard_n2d_standard_64_24SSD'. Production services scale, Development are fixed size. Azure services don't support Development tier

Array of objects (IpAccessListEntry)

List of IP addresses allowed to access the service

minTotalMemoryGb
number multiple of 12 [ 24 .. 708 ]
Deprecated

DEPRECATED - inaccurate for services with non-default numbers of replicas. Minimum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and greater than or equal to 24.

maxTotalMemoryGb
number multiple of 12 [ 24 .. 708 ]
Deprecated

DEPRECATED - inaccurate for services with non-default numbers of replicas. Maximum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and lower than or equal to 360 for non paid services or 708 for paid services.

minReplicaMemoryGb
number multiple of 4 [ 8 .. 236 ]

Minimum total memory of each replica during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 4 and greater than or equal to 8.

maxReplicaMemoryGb
number multiple of 4 [ 8 .. 236 ]

Maximum total memory of each replica during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 4 and lower than or equal to 120 for non paid services or 236 for paid services.

numReplicas
number [ 1 .. 20 ]

Number of replicas for the service. Must be between 1 and 20. Contact support to enable this feature.

idleScaling
boolean

When set to true the service is allowed to scale down to zero when idle. True by default.

idleTimeoutMinutes
number

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

isReadonly
boolean

True if this service is read-only. It can only be read-only if a dataWarehouseId is provided.

dataWarehouseId
string

Data warehouse containing this service

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

releaseChannel
string
Enum: "default" "fast"

Select fast if you want to get new ClickHouse releases as soon as they are available. You'll get new features faster, but with a higher risk of bugs. This feature is only available for production services.

byocId
string

This is the ID returned after setting up a region for Bring Your Own Cloud (BYOC). When the byocId parameter is specified, the minReplicaMemoryGb and the maxReplicaGb parameters are required too, with values included among the following sizes: 28, 60, 124, 188, 252, 380.

Responses

Request samples

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

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
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
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
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
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)
releaseChannel
string
Enum: "default" "fast"

Select fast if you want to get new ClickHouse releases as soon as they are available. You'll get new features faster, but with a higher risk of bugs. This feature is only available for production services.

Responses

Request samples

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

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
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
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
organizationId
required
string <uuid>

ID of the requested organization.

serviceId
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
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
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 Deprecated

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
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
required
string <uuid>

ID of the service to update scaling parameters.

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

DEPRECATED - inaccurate for services with non-default numbers of replicas. Minimum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and greater than or equal to 24.

maxTotalMemoryGb
number multiple of 12 [ 24 .. 708 ]
Deprecated

DEPRECATED - inaccurate for services with non-default numbers of replicas. Maximum memory of three workers during auto-scaling in Gb. Available only for 'production' services. Must be a multiple of 12 and lower than or equal to 360 for non paid services or 708 for paid services.

numReplicas
number [ 1 .. 20 ]

Number of replicas for the service. Must be between 1 and 20. Contact support to enable this feature.

idleScaling
boolean

When set to true the service is allowed to scale down to zero when idle. True by default.

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 auto scaling settings

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

path Parameters
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
required
string <uuid>

ID of the service to update scaling parameters.

Request Body schema: application/json
minReplicaMemoryGb
number multiple of 4 [ 8 .. 236 ]

Minimum auto-scaling memory in Gb for a single replica. Available only for 'production' services. Must be a multiple of 4 and greater than or equal to 8.

maxReplicaMemoryGb
number multiple of 4 [ 8 .. 236 ]

Maximum auto-scaling memory in Gb for a single replica . Available only for 'production' services. Must be a multiple of 4 and lower than or equal to 120 for non paid services or 236 for paid services.

numReplicas
number [ 1 .. 20 ]

Number of replicas for the service. Must be between 1 and 20. Contact support to enable this feature.

idleScaling
boolean

When set to true the service is allowed to scale down to zero when idle. True by default.

idleTimeoutMinutes
number

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

Responses

Request samples

Content type
application/json
{
  • "minReplicaMemoryGb": 16,
  • "maxReplicaMemoryGb": 120,
  • "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
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
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. 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": {
    }
}

Get prometheus metrics

Returns prometheus metrics for a service.

path Parameters
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
required
string <uuid>

ID of the requested service.

query Parameters
filtered_metrics
string <boolean>

Return a filtered list of Prometheus metrics.

Responses

Response samples

Content type
application/json
{
  • "status": 400,
  • "error": "string"
}

List of service backups

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

path Parameters
organizationId
required
string <uuid>

ID of the organization that owns the backup.

serviceId
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
organizationId
required
string <uuid>

ID of the organization that owns the backup.

serviceId
required
string <uuid>

ID of the service the backup was created from.

backupId
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 service backup configuration

Returns the service backup configuration.

path Parameters
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
required
string <uuid>

ID of the service.

Responses

Response samples

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

Update service backup configuration

Updates service backup configuration. Requires ADMIN auth key role. Setting the properties with null value, will reset the properties to theirs default values.

path Parameters
organizationId
required
string <uuid>

ID of the organization that owns the service.

serviceId
required
string <uuid>

ID of the service.

Request Body schema: application/json
backupPeriodInHours
number

The interval in hours between each backup.

backupRetentionPeriodInHours
number

The minimum duration in hours for which the backups are available.

backupStartTime
string

The time in HH:MM format for the backups to be performed (evaluated in UTC timezone). When defined the backup period resets to every 24 hours.

Responses

Request samples

Content type
application/json
{
  • "backupPeriodInHours": 0,
  • "backupRetentionPeriodInHours": 0,
  • "backupStartTime": "string"
}

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
organizationId
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
organizationId
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" "org_member" "billing"

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
organizationId
required
string <uuid>

ID of the requested organization.

keyId
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
organizationId
required
string <uuid>

ID of the organization that owns the key.

keyId
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" "org_member" "billing"

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
organizationId
required
string <uuid>

ID of the organization that owns the key.

keyId
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
organizationId
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
organizationId
required
string <uuid>

ID of the organization the member is part of.

userId
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
organizationId
required
string <uuid>

ID of the organization the member is part of.

userId
required
string <uuid>

ID of the user to patch

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

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
organizationId
required
string <uuid>

ID of the requested organization.

userId
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
organizationId
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
organizationId
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" "org_member" "billing"

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
organizationId
required
string <uuid>

ID of the requested organization.

invitationId
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
organizationId
required
string <uuid>

ID of the organization that has the invitation.

invitationId
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
organizationId
required
string <uuid>

ID of the requested organization.

query Parameters
from_date
string <date-time>

A starting date for a search

to_date
string <date-time>

An ending date for a search

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
organizationId
required
string <uuid>

ID of the requested organization.

activityId
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
organizationId
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": {
    }
}