/v1/organizations/{organizationId}/servicesCreates a new service in the organization, and returns the current service state and a password to access the service. The service is started asynchronously.
Permission
The API key must have the control-plane:organization:create-service and control-plane:service:manage permissions.
Path parameters
Request bodyJSON
- tierdeprecateddevelopmentorproduction
DEPRECATED for BASIC, SCALE and ENTERPRISE organization tiers. Use
minReplicaMemoryGb,maxReplicaMemoryGb, andnumReplicasinstead. Tier of the service: 'development', 'production'. Production services scale, Development are fixed size. Azure services don't support Development tier - minTotalMemoryGbdeprecatednumber
DEPRECATED - inaccurate for services with non-default numbers of replicas. Use
minReplicaMemoryGbinstead. 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).maximum: 1068, minimum: 24Example: 48 - maxTotalMemoryGbdeprecatednumber
DEPRECATED - inaccurate for services with non-default numbers of replicas. Use
maxReplicaMemoryGbinstead. 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).maximum: 1068, minimum: 24Example: 360 - autoscalingModeoptionalverticalorhorizontal
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.
Example: "vertical" - minReplicaMemoryGboptionalnumber
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.
maximum: 356, minimum: 8Example: 16 - maxReplicaMemoryGboptionalnumber
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.
maximum: 356, minimum: 8Example: 120 - minReplicasoptionalinteger
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).
maximum: 50, minimum: 1Example: 1 - maxReplicasoptionalinteger
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).
maximum: 50, minimum: 1Example: 5 - backupIdoptionalstring
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. If the backup is stored in your organization's own bucket,
backupEncryptionConfigis required; it must be omitted otherwise.format: uuid - backupEncryptionConfigoptionalobject
The
encryption_config.jsonstored alongside this backup in your bucket, passed through unchanged. Supply the file contents verbatim rather than constructing this object — its shape is versioned and depends on your cloud provider. See Export backups to your own cloud account for what it contains.Accepted only for organizations enrolled in the private preview, and only when the backup is of a service that has transparent data encryption enabled. Such a restore always produces a service with transparent data encryption enabled, inherited from the source service.
Example: {"schema_version":1,"restore_key_pairs":[{"customer_managed_encryption_key":{"aws_kms_key_arn":"arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"},"encrypted_dek":"<base64 wrapped data encryption key>"}]} - releaseChanneloptionalslowordefaultorfast
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.
- byocIdoptionalstring
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 maxReplicaMemoryGb parameters are required too. With a BYOC profile, both must equal that profile's memory size. Without a profile, equal values must be one of the following sizes: 48, 116, 172, 232. When BYOC vertical autoscaling is enabled for the organization (contact support), a minReplicaMemoryGb lower than maxReplicaMemoryGb, without a profile, creates a service that scales vertically between the two. Both values must be memory sizes listed by the serviceProfiles endpoint, and the service reports the profile 'v1-default'.
- profileoptionalstring
Custom instance profile. Profiles other than v1-default and v2-default are only available for ENTERPRISE and BYOC organization tiers. Standard values: 'v1-default', 'v2-default', 'v1-highmem-xs', 'v1-highmem-s', 'v1-highmem-m', 'v1-highmem-l', 'v1-highmem-xl'. 'v2-default' is Gen 2 hardware. BYOC services may instead use a dynamic BYOC profile configured for their infrastructure (e.g. 'v1-standard-byoc-4'); it requires byocId, and minReplicaMemoryGb and maxReplicaMemoryGb must both equal the profile's memory size. A BYOC service that scales vertically within a memory range has no BYOC profile and reports 'v1-default'. Use the serviceProfiles endpoint to list the profiles available to the organization. Creating a 'v2-default' service needs Gen 2 enabled for the organization and included in its plan (SCALE or ENTERPRISE) or settings, an AWS region where Gen 2 is available, and no byocId (BYOC infrastructure is not supported). Gen 2 services use a fixed size: minReplicaMemoryGb must equal maxReplicaMemoryGb and the replica count is fixed (numReplicas, or equal minReplicas and maxReplicas). Gen 2 services cannot idle: send idleScaling as false, since it defaults to true.
- deletionProtectionoptionalboolean
When true, the service cannot be deleted: the delete endpoint returns 409 until deletion protection is turned off. Default is false. Setting it to true requires the
control-plane:service:deletepermission granted for all services in the organization (not service by service), in addition tocontrol-plane:organization:create-service.
Response
200
Successful response
400
The request cannot be processed due to a client error. Please verify your request parameters and try again.
500
An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.