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.

POST /v1/organizations/{organizationId}/services

Create new service

cURL

curl --request POST \
  --url https://api.clickhouse.cloud/v1/organizations/{organizationId}/services \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "provider": "aws",
  "region": "ap-northeast-1",
  "tier": "development",
  "ipAccessList": [
    {
      "source": "<string>",
      "description": "<string>"
    }
  ],
  "minTotalMemoryGb": 48,
  "maxTotalMemoryGb": 360,
  "minReplicaMemoryGb": 16,
  "maxReplicaMemoryGb": 120,
  "numReplicas": 3,
  "idleScaling": true,
  "idleTimeoutMinutes": 123,
  "isReadonly": true,
  "dataWarehouseId": "<string>",
  "backupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "encryptionKey": "<string>",
  "encryptionAssumedRoleIdentifier": "<string>",
  "privateEndpointIds": [
    "<string>"
  ],
  "privatePreviewTermsChecked": true,
  "releaseChannel": "slow",
  "byocId": "<string>",
  "hasTransparentDataEncryption": true,
  "endpoints": [
    {
      "protocol": "mysql",
      "enabled": true
    }
  ],
  "profile": "v1-default",
  "complianceType": "hipaa"
}
'

200

{
  "status": 200,
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "result": {
    "service": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "provider": "aws",
      "region": "ap-northeast-1",
      "state": "starting",
      "clickhouseVersion": "<string>",
      "endpoints": [
        {
          "protocol": "mysql",
          "host": "<string>",
          "port": 123,
          "username": "<string>"
        }
      ],
      "tier": "development",
      "minTotalMemoryGb": 48,
      "maxTotalMemoryGb": 360,
      "minReplicaMemoryGb": 16,
      "maxReplicaMemoryGb": 120,
      "numReplicas": 3,
      "idleScaling": true,
      "idleTimeoutMinutes": 123,
      "ipAccessList": [
        {
          "source": "<string>",
          "description": "<string>"
        }
      ],
      "createdAt": "2023-11-07T05:31:56Z",
      "encryptionKey": "<string>",
      "encryptionAssumedRoleIdentifier": "<string>",
      "iamRole": "<string>",
      "privateEndpointIds": [
        "<string>"
      ],
      "availablePrivateEndpointIds": [
        "<string>"
      ],
      "dataWarehouseId": "<string>",
      "isPrimary": true,
      "isReadonly": true,
      "releaseChannel": "slow",
      "byocId": "<string>",
      "hasTransparentDataEncryption": true,
      "profile": "v1-default",
      "transparentDataEncryptionKeyId": "<string>",
      "encryptionRoleId": "<string>",
      "complianceType": "hipaa"
    },
    "password": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi

Path Parameters

organizationId · string<uuid> · required

ID of the organization that will own the service.

Body

application/json

name · string

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

provider · enum<string>

Cloud provider

Available options: aws, gcp, azure

region · enum<string>

Service region.

Available options: ap-northeast-1, ap-south-1, ap-southeast-1, ap-southeast-2, eu-central-1, eu-west-1, eu-west-2, me-central-1, us-east-1, us-east-2, us-west-2, us-east1, us-central1, europe-west4, asia-southeast1, eastus, eastus2, westus3, germanywestcentral

tier · enum<string> · deprecated

DEPRECATED for BASIC, SCALE and ENTERPRISE organization tiers. 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

Available options: 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

ipAccessList · object[]

List of IP addresses allowed to access the service

Show child attributes

minTotalMemoryGb · number · 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.

Required range: 24 <= x <= 1068Must be a multiple of 12

Example:

48

maxTotalMemoryGb · number · 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 1068 for paid services.

Required range: 24 <= x <= 1068Must be a multiple of 12

Example:

360

minReplicaMemoryGb · number

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

Required range: 8 <= x <= 356Must be a multiple of 4

Example:

16

maxReplicaMemoryGb · number

Maximum total memory of each replica during auto-scaling in Gb. Must be a multiple of 4 and lower than or equal to 120* for non paid services or 356* for paid services.* - maximum replica size subject to cloud provider hardware availability in your selected region.

Required range: 8 <= x <= 356Must be a multiple of 4

Example:

120

numReplicas · number

Number of replicas for the service. The number of replicas must be between 2 and 20 for the first service in a warehouse. Services that are created in an existing warehouse can have a number of replicas as low as 1. Further restrictions may apply based on your organization's tier. It defaults to 1 for the BASIC tier and 3 for the SCALE and ENTERPRISE tiers.

Required range: 1 <= x <= 20

Example:

3

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 · string[] · deprecated

To associate the service with private endpoints, first create the service, then use the Update Service Basic Details endpoint to modify 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 · enum<string>

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. Select slow if you would like to defer releases to give yourself more time to test. This feature is only available for production services. default is the regular release channel.

Available options: slow, default, fast

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: 48, 116, 172, 232.

hasTransparentDataEncryption · boolean

True if the service should have the Transparent Data Encryption (TDE) enabled. TDE is only available for ENTERPRISE organizations tiers and can only be enabled at service creation.

endpoints · object[]

List of service endpoints to enable or disable

Show child attributes

profile · enum<string>

Custom instance profile. Only available for ENTERPRISE organization tiers.

Available options: v1-default, v1-highmem-xs, v1-highmem-s, v1-highmem-m, v1-highmem-l, v1-highmem-xl, v1-highcpu-s, v1-highcpu-m, v1-highcpu-l, v1-highcpu-xl

complianceType · enum<string>

Type of regulatory compliance for service.

Available options: hipaa, pci

Response

200

application/json

Successful response

status · number

HTTP status code.

Example:

200

requestId · string<uuid>

Unique id assigned to every request. UUIDv4

result · object

Show child attributes