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>",
  "ipAccessList": [
    {
      "source": "<string>",
      "description": "<string>"
    }
  ],
  "minTotalMemoryGb": 48,
  "maxTotalMemoryGb": 360,
  "autoscalingMode": "vertical",
  "minReplicaMemoryGb": 16,
  "maxReplicaMemoryGb": 120,
  "numReplicas": 3,
  "minReplicas": 1,
  "maxReplicas": 5,
  "idleScaling": true,
  "idleTimeoutMinutes": 123,
  "isReadonly": true,
  "dataWarehouseId": "<string>",
  "backupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "encryptionKey": "<string>",
  "encryptionAssumedRoleIdentifier": "<string>",
  "privateEndpointIds": [
    "<string>"
  ],
  "privatePreviewTermsChecked": true,
  "byocId": "<string>",
  "hasTransparentDataEncryption": true,
  "endpoints": [
    {
      "protocol": "mysql",
      "enabled": true
    }
  ],
  "tags": [
    {
      "key": "Environment",
      "value": "staging"
    }
  ],
  "enableCoreDumps": true
}
'

import requests

url = "https://api.clickhouse.cloud/v1/organizations/{organizationId}/services"

payload = {
    "name": "<string>",
    "ipAccessList": [
        {
            "source": "<string>",
            "description": "<string>"
        }
    ],
    "minTotalMemoryGb": 48,
    "maxTotalMemoryGb": 360,
    "autoscalingMode": "vertical",
    "minReplicaMemoryGb": 16,
    "maxReplicaMemoryGb": 120,
    "numReplicas": 3,
    "minReplicas": 1,
    "maxReplicas": 5,
    "idleScaling": True,
    "idleTimeoutMinutes": 123,
    "isReadonly": True,
    "dataWarehouseId": "<string>",
    "backupId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "encryptionKey": "<string>",
    "encryptionAssumedRoleIdentifier": "<string>",
    "privateEndpointIds": ["<string>"],
    "privatePreviewTermsChecked": True,
    "byocId": "<string>",
    "hasTransparentDataEncryption": True,
    "endpoints": [
        {
            "protocol": "mysql",
            "enabled": True
        }
    ],
    "tags": [
        {
            "key": "Environment",
            "value": "staging"
        }
    ],
    "enableCoreDumps": True
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    ipAccessList: [{source: '<string>', description: '<string>'}],
    minTotalMemoryGb: 48,
    maxTotalMemoryGb: 360,
    autoscalingMode: 'vertical',
    minReplicaMemoryGb: 16,
    maxReplicaMemoryGb: 120,
    numReplicas: 3,
    minReplicas: 1,
    maxReplicas: 5,
    idleScaling: true,
    idleTimeoutMinutes: 123,
    isReadonly: true,
    dataWarehouseId: '<string>',
    backupId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    encryptionKey: '<string>',
    encryptionAssumedRoleIdentifier: '<string>',
    privateEndpointIds: ['<string>'],
    privatePreviewTermsChecked: true,
    byocId: '<string>',
    hasTransparentDataEncryption: true,
    endpoints: [{protocol: 'mysql', enabled: true}],
    tags: [{key: 'Environment', value: 'staging'}],
    enableCoreDumps: true
  })
};

fetch('https://api.clickhouse.cloud/v1/organizations/{organizationId}/services', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.clickhouse.cloud/v1/organizations/{organizationId}/services",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'ipAccessList' => [
        [
                'source' => '<string>',
                'description' => '<string>'
        ]
    ],
    'minTotalMemoryGb' => 48,
    'maxTotalMemoryGb' => 360,
    'autoscalingMode' => 'vertical',
    'minReplicaMemoryGb' => 16,
    'maxReplicaMemoryGb' => 120,
    'numReplicas' => 3,
    'minReplicas' => 1,
    'maxReplicas' => 5,
    'idleScaling' => true,
    'idleTimeoutMinutes' => 123,
    'isReadonly' => true,
    'dataWarehouseId' => '<string>',
    'backupId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'encryptionKey' => '<string>',
    'encryptionAssumedRoleIdentifier' => '<string>',
    'privateEndpointIds' => [
        '<string>'
    ],
    'privatePreviewTermsChecked' => true,
    'byocId' => '<string>',
    'hasTransparentDataEncryption' => true,
    'endpoints' => [
        [
                'protocol' => 'mysql',
                'enabled' => true
        ]
    ],
    'tags' => [
        [
                'key' => 'Environment',
                'value' => 'staging'
        ]
    ],
    'enableCoreDumps' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.clickhouse.cloud/v1/organizations/{organizationId}/services"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"ipAccessList\": [\n    {\n      \"source\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"minTotalMemoryGb\": 48,\n  \"maxTotalMemoryGb\": 360,\n  \"autoscalingMode\": \"vertical\",\n  \"minReplicaMemoryGb\": 16,\n  \"maxReplicaMemoryGb\": 120,\n  \"numReplicas\": 3,\n  \"minReplicas\": 1,\n  \"maxReplicas\": 5,\n  \"idleScaling\": true,\n  \"idleTimeoutMinutes\": 123,\n  \"isReadonly\": true,\n  \"dataWarehouseId\": \"<string>\",\n  \"backupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"encryptionKey\": \"<string>\",\n  \"encryptionAssumedRoleIdentifier\": \"<string>\",\n  \"privateEndpointIds\": [\n    \"<string>\"\n  ],\n  \"privatePreviewTermsChecked\": true,\n  \"byocId\": \"<string>\",\n  \"hasTransparentDataEncryption\": true,\n  \"endpoints\": [\n    {\n      \"protocol\": \"mysql\",\n      \"enabled\": true\n    }\n  ],\n  \"tags\": [\n    {\n      \"key\": \"Environment\",\n      \"value\": \"staging\"\n    }\n  ],\n  \"enableCoreDumps\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.clickhouse.cloud/v1/organizations/{organizationId}/services")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"ipAccessList\": [\n    {\n      \"source\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"minTotalMemoryGb\": 48,\n  \"maxTotalMemoryGb\": 360,\n  \"autoscalingMode\": \"vertical\",\n  \"minReplicaMemoryGb\": 16,\n  \"maxReplicaMemoryGb\": 120,\n  \"numReplicas\": 3,\n  \"minReplicas\": 1,\n  \"maxReplicas\": 5,\n  \"idleScaling\": true,\n  \"idleTimeoutMinutes\": 123,\n  \"isReadonly\": true,\n  \"dataWarehouseId\": \"<string>\",\n  \"backupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"encryptionKey\": \"<string>\",\n  \"encryptionAssumedRoleIdentifier\": \"<string>\",\n  \"privateEndpointIds\": [\n    \"<string>\"\n  ],\n  \"privatePreviewTermsChecked\": true,\n  \"byocId\": \"<string>\",\n  \"hasTransparentDataEncryption\": true,\n  \"endpoints\": [\n    {\n      \"protocol\": \"mysql\",\n      \"enabled\": true\n    }\n  ],\n  \"tags\": [\n    {\n      \"key\": \"Environment\",\n      \"value\": \"staging\"\n    }\n  ],\n  \"enableCoreDumps\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.clickhouse.cloud/v1/organizations/{organizationId}/services")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"ipAccessList\": [\n    {\n      \"source\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"minTotalMemoryGb\": 48,\n  \"maxTotalMemoryGb\": 360,\n  \"autoscalingMode\": \"vertical\",\n  \"minReplicaMemoryGb\": 16,\n  \"maxReplicaMemoryGb\": 120,\n  \"numReplicas\": 3,\n  \"minReplicas\": 1,\n  \"maxReplicas\": 5,\n  \"idleScaling\": true,\n  \"idleTimeoutMinutes\": 123,\n  \"isReadonly\": true,\n  \"dataWarehouseId\": \"<string>\",\n  \"backupId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"encryptionKey\": \"<string>\",\n  \"encryptionAssumedRoleIdentifier\": \"<string>\",\n  \"privateEndpointIds\": [\n    \"<string>\"\n  ],\n  \"privatePreviewTermsChecked\": true,\n  \"byocId\": \"<string>\",\n  \"hasTransparentDataEncryption\": true,\n  \"endpoints\": [\n    {\n      \"protocol\": \"mysql\",\n      \"enabled\": true\n    }\n  ],\n  \"tags\": [\n    {\n      \"key\": \"Environment\",\n      \"value\": \"staging\"\n    }\n  ],\n  \"enableCoreDumps\": true\n}"

response = http.request(request)
puts response.read_body

200

{
  "status": 200,
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "result": {
    "service": {
      "autoscalingMode": "vertical",
      "currentScaling": {
        "effectiveMinReplicaMemoryGb": 123,
        "effectiveMaxReplicaMemoryGb": 123,
        "effectiveMinReplicas": 123,
        "effectiveMaxReplicas": 123,
        "effectiveIdleScaling": true,
        "effectiveIdleTimeoutMinutes": 123,
        "activeEntryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "clickhouseVersion": "<string>",
      "endpoints": [
        {
          "protocol": "mysql",
          "host": "<string>",
          "port": 123,
          "username": "<string>"
        }
      ],
      "minTotalMemoryGb": 48,
      "maxTotalMemoryGb": 360,
      "minReplicaMemoryGb": 16,
      "maxReplicaMemoryGb": 120,
      "numReplicas": 3,
      "minReplicas": 1,
      "maxReplicas": 5,
      "replicaMemoryGb": 32,
      "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,
      "byocId": "<string>",
      "hasTransparentDataEncryption": true,
      "transparentDataEncryptionKeyId": "<string>",
      "encryptionRoleId": "<string>",
      "tags": [
        {
          "key": "Environment",
          "value": "staging"
        }
      ],
      "enableCoreDumps": true,
      "scalingSchedule": {
        "entries": [
          {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "name": "<string>",
            "weekdays": [
              123
            ],
            "startHourUtc": 11,
            "endHourUtc": 12,
            "isActiveNow": true,
            "minReplicaMemoryGb": 123,
            "maxReplicaMemoryGb": 123,
            "minReplicas": 123,
            "maxReplicas": 123,
            "idleScaling": true,
            "idleTimeoutMinutes": 123
          }
        ],
        "baseConfig": {
          "minReplicaMemoryGb": 123,
          "maxReplicaMemoryGb": 123,
          "minReplicas": 123,
          "maxReplicas": 123,
          "idleScaling": true,
          "idleTimeoutMinutes": 123
        },
        "activeEntryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    },
    "password": "<string>"
  }
}

{
  "status": 400,
  "error": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "status": 500,
  "error": "<string>",
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

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.

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.

Required string length: 1 - 50

provider · enum<string>

Cloud provider

Available options: aws, gcp, azure

region · enum<string>

Service region.

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

tier · enum<string> · deprecated

DEPRECATED for BASIC, SCALE and ENTERPRISE organization tiers. Use minReplicaMemoryGb, maxReplicaMemoryGb, and numReplicas instead. 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. Use minReplicaMemoryGb instead. 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. Always absent for horizontal-autoscaling services (replica count is variable).

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. Use maxReplicaMemoryGb instead. 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. Always absent for horizontal-autoscaling services (replica count is variable).

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

Example:

360

autoscalingMode · enum<string>

Autoscaling mode. "vertical" (the default when omitted) runs a fixed replica count while memory scales between minReplicaMemoryGb and maxReplicaMemoryGb; "horizontal" scales the replica count between minReplicas and maxReplicas at a fixed per-replica memory (minReplicaMemoryGb equal to maxReplicaMemoryGb). Horizontal requires the feature to be enabled for the organization.

Available options: vertical, horizontal

Example:

"vertical"

minReplicaMemoryGb · number

Minimum total memory of each replica during auto-scaling in Gb. A range in vertical autoscaling; equal to maxReplicaMemoryGb in horizontal (memory is fixed while the replica count scales). 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. A range in vertical autoscaling; equal to minReplicaMemoryGb in horizontal (memory is fixed while the replica count scales). 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 · integer

Fixed replica count for vertical autoscaling (autoscalingMode "vertical" or omitted). Mutually exclusive with minReplicas/maxReplicas.

Required range: 1 <= x <= 20

Example:

3

minReplicas · integer

Minimum number of replicas. A minReplicas/maxReplicas band scales the replica count in horizontal autoscaling (autoscalingMode "horizontal"). Must be provided together with maxReplicas. Mutually exclusive with numReplicas. Requires horizontal autoscaling to be enabled for the organization, unless autoscalingMode is omitted or "vertical" and minReplicas equals maxReplicas (an equal band is then an accepted vertical fixed count and needs no horizontal entitlement).

Required range: 1 <= x <= 20

Example:

1

maxReplicas · integer

Maximum number of replicas. A minReplicas/maxReplicas band scales the replica count in horizontal autoscaling (autoscalingMode "horizontal"). Must be provided together with minReplicas. Mutually exclusive with numReplicas. Requires horizontal autoscaling to be enabled for the organization, unless autoscalingMode is omitted or "vertical" and minReplicas equals maxReplicas (an equal band is then an accepted vertical fixed count and needs no horizontal entitlement).

Required range: 1 <= x <= 20

Example:

5

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

DEPRECATED. To associate the service with private endpoints, first create the service, then use the Update Service Basic Details endpoint with the privateEndpointIds field 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

complianceType · enum<string>

Type of regulatory compliance for service.

Available options: hipaa, pci

tags · object[]

Tags associated with the service.

Maximum array length: 50

Show child attributes

enableCoreDumps · boolean

Enables the underlying infra for collecting core dumps. Default is enabled.

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