openapi: 3.2.0 info: title: OpenAPI spec for ClickHouse Cloud Service API version: '1.0' contact: name: ClickHouse Support url: https://clickhouse.com/docs/en/cloud/manage/openapi?referrer=openapi-1107336 email: support@clickhouse.com servers: - url: https://api.clickhouse.cloud security: - basicAuth: [] tags: - name: Service paths: /v1/organizations/{organizationId}/serviceProfiles: get: summary: List available service profiles description: Returns the custom instance profiles the organization can use in a region. Pass byoc_id to list the profiles configured for a BYOC infrastructure. The list is empty when the organization tier does not include custom hardware profiles. operationId: serviceProfilesList parameters: - in: path name: organizationId description: ID of the organization to list available profiles for. required: true schema: type: string format: uuid - in: query name: region_id description: Region to list profiles for, e.g. us-east-1. schema: type: string required: true - in: query name: byoc_id description: ID of the BYOC infrastructure to list profiles for. BYOC profiles are only returned when this is set. schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: type: array items: $ref: '#/components/schemas/ServiceProfile' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services: get: summary: List of organization services description: Returns a list of all services in the organization. operationId: instanceGetList parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: query name: filter description: Filter criteria to apply when retrieving the resource. Currently, only filtering by resource tags is supported. schema: type: array items: type: string example: - tag:Environment=Production - tag:Department=Engineering - tag:isActive responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: type: array items: $ref: '#/components/schemas/Service' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service post: summary: Create new service description: 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. operationId: instanceCreate parameters: - in: path name: organizationId description: ID of the organization that will own the service. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServicePostRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServicePostResponse' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}: get: summary: Get service details description: Returns a service that belongs to the organization operationId: instanceGet parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the requested service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/Service' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service patch: summary: Update service basic details description: Updates basic service details like service name or IP access list. operationId: instanceUpdate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service to update. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServicePatchRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/Service' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service delete: summary: Delete service description: Deletes the service. The service must be in stopped state and is deleted asynchronously after this method call. operationId: instanceDelete parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service to delete. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig: get: summary: Get private endpoint configuration description: Information required to set up a private endpoint operationId: instancePrivateEndpointConfigGet parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the requested service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/PrivateEndpointConfig' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint: get: summary: Get the service query endpoint for a given instance description: Get the configuration for the service query endpoint that allows executing queries via API. operationId: instanceQueryEndpointGet parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the requested service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServiceQueryAPIEndpoint' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service delete: summary: Delete the service query endpoint for a given instance description: Removes the service query endpoint. operationId: instanceQueryEndpointDelete parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the requested service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service post: summary: Upsert the service query endpoint for a given instance description: Create the service query endpoint that allows executing queries via API. operationId: instanceQueryEndpointUpsert parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the requested service. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/InstanceServiceQueryApiEndpointsPostRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServiceQueryAPIEndpoint' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/state: patch: summary: Update service state description: Starts, stops, or wakes a service. The `start` and `stop` commands require the `control-plane:service:manage` permission on the service. The `awake` command requires only `control-plane:service:view` and applies to an idle service; it does not start a stopped service. operationId: instanceStateUpdate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service to update state. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServiceStatePatchRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/Service' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/scaling: patch: summary: Update service auto scaling settings description: 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. operationId: instanceScalingUpdate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service to update scaling parameters. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServiceScalingPatchRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/Service' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid deprecated: true tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/replicaScaling: patch: summary: Update service auto scaling settings description: Updates minimum and maximum memory limits per replica and idle mode scaling behavior for the service. Supports both vertical autoscaling (fixed replica count, variable memory) and horizontal autoscaling (variable replica count, fixed memory). The memory settings are available only for "production" services and must be a multiple of 4 starting from 8GB. For vertical autoscaling, please contact support to enable adjustment of numReplicas. For horizontal autoscaling (autoscalingMode "horizontal" with minReplicas/maxReplicas), contact support to enable the feature for your organization. operationId: instanceReplicaScalingUpdate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service to update scaling parameters. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServiceReplicaScalingPatchRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServiceScalingPatchResponse' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/password: patch: summary: Update service password description: Sets a new password for the service operationId: instancePasswordUpdate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service to update password. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServicePasswordPatchRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServicePasswordPatchResponse' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint: post: summary: Create a private endpoint description: Create a new private endpoint. The private endpoint will be associated with this service and organization operationId: instancePrivateEndpointCreate parameters: - in: path name: organizationId description: ID of the requested organization. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the requested service. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServicPrivateEndpointePostRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/InstancePrivateEndpoint' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/scalingSchedule: get: summary: Get service autoscaling schedule description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Returns the autoscaling schedule for a service. Returns 404 if no schedule has been configured or if the schedule was cleared. Requires the scheduled autoscaling feature to be enabled for the organization.' operationId: scalingScheduleGet parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ScalingSchedule' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after post: summary: Create or replace service autoscaling schedule description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Creates or fully replaces the autoscaling schedule for a service. Pass an empty `entries` array to clear the schedule — a subsequent GET will return 404, and the response will contain an empty `baseConfig` (all fields absent). The base scaling config (applied when no entry is active) is managed separately via the `replicaScaling` endpoint. Requires the scheduled autoscaling feature to be enabled for the organization.' operationId: scalingScheduleUpsert parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ScalingSchedulePostRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ScalingSchedule' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after delete: summary: Delete service scheduled scaling description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Deletes the autoscaling schedule for a service. If a schedule entry is currently active, the base scaling config is restored to the instance before the schedule is removed. Returns 404 if no schedule exists. Requires the scheduled autoscaling feature to be enabled for the organization.' operationId: scalingScheduleDelete parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after /v1/organizations/{organizationId}/services/{serviceId}/upgradeWindow: get: summary: Get service upgrade window description: 'Returns the configured upgrade window for a service. Errors: - 401: missing, invalid, or disabled API key. - 403: caller lacks `control-plane:service:view` on the service. - 404: service does not exist, is not visible to the caller, or no upgrade window has been configured.' operationId: upgradeWindowGet parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/UpgradeWindow' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service put: summary: Set service upgrade window description: 'Creates or fully replaces the upgrade window for a service. The upgrade window currently lasts 6 hours from `startHourUtc`. The upgrade window can only be set on primary services; secondary services inherit the primary service window. Errors: - 400: invalid field values (`weekday` not in 0–6, `startHourUtc` not in {0, 6, 12, 18}), or the service is a secondary service. - 401: missing, invalid, or disabled API key. - 403: caller lacks `control-plane:service:manage` on the service, or the organization does not have the scheduled upgrades feature enabled. - 404: service does not exist or is not visible to the caller.' operationId: upgradeWindowUpdate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/UpgradeWindowPutRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/UpgradeWindow' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service delete: summary: Delete service upgrade window description: 'Deletes the upgrade window for a service, restoring the default scheduling behaviour. The upgrade window can only be deleted on primary services. Deletion succeeds even if the organization has lost the scheduled upgrades entitlement, so a window can be cleared after entitlement loss. Errors: - 400: the service is a secondary service. - 401: missing, invalid, or disabled API key. - 403: caller lacks `control-plane:service:manage` on the service. - 404: service does not exist, is not visible to the caller, or no upgrade window is configured.' operationId: upgradeWindowDelete parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service /v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings: get: summary: List ClickHouse settings description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Returns the configured ClickHouse settings for the service. Only settings that have been explicitly set are included.' operationId: serviceClickhouseSettingsListGet parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServiceClickhouseSettingsList' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after patch: summary: Update ClickHouse settings description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Updates one or more ClickHouse settings for the service. To reset a setting to its platform default, use the DELETE single setting endpoint. Use the schema endpoint to discover which settings are configurable.' operationId: serviceClickhouseSettingsUpdate parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/ServiceClickhouseSettingsPatchRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServiceClickhouseSettingsPatchResponse' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after /v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings/schema: get: summary: Get ClickHouse settings schema description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Returns the schema of all configurable ClickHouse settings, including types, valid values, descriptions, and warnings.' operationId: serviceClickhouseSettingsSchemaGet parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServiceClickhouseSettingsSchema' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after /v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings/{settingName}: get: summary: Get ClickHouse setting description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Returns the current value of a ClickHouse setting for the service. Use the schema endpoint to discover which settings are configurable.' operationId: serviceClickhouseSettingGet parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid - in: path name: settingName description: Name of the setting to retrieve. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid result: $ref: '#/components/schemas/ServiceClickhouseSetting' '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after delete: summary: Reset ClickHouse setting to default description: '**Disclaimer:** This beta endpoint is evolving; the API contract may change. Removes a previously-configured ClickHouse setting, reverting its effective value to the platform default. Settings under `spec.extraConfig.server.*` (e.g. `keep_alive_timeout`, `shared_merge_tree_disable_merges_and_mutations_assignment`) trigger a ClickHouse server rollout restart; other settings propagate to all replicas after a short delay. Deleting a setting that was never configured is a no-op (200 OK).' operationId: serviceClickhouseSettingDelete parameters: - in: path name: organizationId description: ID of the organization that owns the service. required: true schema: type: string format: uuid - in: path name: serviceId description: ID of the service. required: true schema: type: string format: uuid - in: path name: settingName description: Name of the setting to reset. required: true schema: type: string responses: '200': description: Successful response content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 200 requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '400': description: The request cannot be processed due to a client error. Please verify your request parameters and try again. content: application/json: schema: type: object properties: status: type: number description: HTTP status code. example: 400 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid '500': description: An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance. content: application/json: schema: type: object properties: status: type: integer description: HTTP status code. example: 500 error: type: string description: Detailed error description. requestId: type: string description: Unique id assigned to every request. UUIDv4 format: uuid tags: - Service x-badges: - name: Beta position: after components: schemas: IpAccessListPatch: properties: add: type: array description: Elements to add. Executed after "remove" part is processed. items: $ref: '#/components/schemas/IpAccessListEntry' remove: type: array description: Elements to remove. Executed before "add" part is processed. items: $ref: '#/components/schemas/IpAccessListEntry' UpgradeWindowPutRequest: properties: weekday: description: Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, …, 6 = Saturday. type: integer minimum: 0 maximum: 6 example: 3 startHourUtc: description: UTC hour when the upgrade window starts. Must be one of 0, 6, 12, or 18. The upgrade window currently lasts 6 hours from this start time. type: integer enum: - 0 - 6 - 12 - 18 example: 12 required: - weekday - startHourUtc ServicePasswordPatchResponse: properties: password: description: New service password. Provided only if there was no 'newPasswordHash' in the request type: string ScalingSchedule: properties: entries: type: array description: List of schedule entries. items: $ref: '#/components/schemas/ScalingScheduleEntry' baseConfig: $ref: '#/components/schemas/ScalingScheduleBaseConfig' activeEntryId: description: ID of the currently-active schedule entry. Absent when no entry is active and the base config is in effect. type: string format: uuid required: - entries - baseConfig InstanceServiceQueryApiEndpointsPostRequest: properties: roles: type: array description: The roles items: type: string enum: - sql_console_read_only - sql_console_admin openApiKeys: type: array description: The version of the service query endpoint items: type: string allowedOrigins: description: The allowed origins as comma separated list of domains type: string ServiceClickhouseSettingsSchema: properties: settings: type: array description: List of all configurable ClickHouse settings with their types, descriptions, and constraints. items: $ref: '#/components/schemas/ServiceClickhouseSettingSchemaEntry' InstancePrivateEndpointsPatch: properties: add: type: array description: Elements to add. Executed after "remove" part is processed. items: type: string remove: type: array description: Elements to remove. Executed before "add" part is processed. items: type: string ServiceScalingPatchRequest: properties: minTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 48 deprecated: true maxTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 360 deprecated: true numReplicas: description: 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. type: integer minimum: 1 maximum: 20 example: 3 idleScaling: description: When set to true the service is allowed to scale down to zero when idle. True by default. type: boolean idleTimeoutMinutes: description: Set minimum idling timeout (in minutes). Must be >= 5 minutes. type: number IpAccessListEntry: properties: source: description: IP or CIDR type: string description: description: Optional description of IPv4 address or IPv4 CIDR to allow access from type: string ServiceStatePatchRequest: properties: command: description: 'Command to change the state: ''start'', ''stop'', ''awake''.' type: string enum: - start - stop - awake ServiceClickhouseSettingWarning: properties: name: description: Name of the setting the warning applies to. type: string example: compatibility message: description: Warning message. type: string example: Changing the compatibility version without comprehensive testing can cause query failures or instability. InstanceTagsPatch: properties: add: type: array description: Elements to add. Executed after "remove" part is processed. items: $ref: '#/components/schemas/ResourceTagsV1' maxItems: 50 remove: type: array description: Elements to remove. Executed before "add" part is processed. items: $ref: '#/components/schemas/ResourceTagsV1' maxItems: 50 UpgradeWindow: properties: weekday: description: Day of the week the upgrade window starts. 0 = Sunday, 1 = Monday, …, 6 = Saturday. type: integer minimum: 0 maximum: 6 example: 3 startHourUtc: description: UTC hour when the upgrade window starts. Must be one of 0, 6, 12, or 18. type: integer enum: - 0 - 6 - 12 - 18 example: 12 duration: description: Length of the upgrade window in hours. Currently only a 6-hour window is supported. type: integer enum: - 6 example: 6 required: - weekday - startHourUtc - duration ServiceQueryAPIEndpoint: properties: id: description: The id of the service query endpoint type: string openApiKeys: type: array description: List of OpenAPI keys that can access the service query endpoint items: type: string roles: type: array description: List of roles that can access the service query endpoint items: type: string enum: - sql_console_read_only - sql_console_admin allowedOrigins: description: The allowed origins as comma separated list of domains type: string ServicePostResponse: properties: service: $ref: '#/components/schemas/Service' password: description: Password for the newly created service. type: string Service: properties: id: description: Unique service ID. type: string format: uuid name: description: Name of the service. Alphanumerical string with whitespaces up to 50 characters. type: string maxLength: 50 minLength: 1 provider: description: Cloud provider type: string enum: - aws - gcp - azure region: description: Service region. type: string enum: - 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 state: description: Current state of the service. type: string enum: - starting - stopping - terminating - softdeleting - awaking - partially_running - provisioning - running - stopped - terminated - softdeleted - degraded - failed - idle clickhouseVersion: description: ClickHouse version of the service. type: string endpoints: type: array description: List of all service endpoints. items: $ref: '#/components/schemas/ServiceEndpoint' tier: description: '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' type: 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 deprecated: true minTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 48 deprecated: true maxTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 360 deprecated: true minReplicaMemoryGb: description: 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. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 16 maxReplicaMemoryGb: description: '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. ' type: number minimum: 8 maximum: 356 multipleOf: 4 example: 120 numReplicas: description: 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. Present only when the service uses vertical autoscaling. For horizontal autoscaling, use minReplicas and maxReplicas instead. type: integer minimum: 1 maximum: 20 example: 3 minReplicas: description: Minimum number of replicas for horizontal autoscaling. Present only when the service uses horizontal autoscaling. type: integer minimum: 1 maximum: 20 example: 1 maxReplicas: description: Maximum number of replicas for horizontal autoscaling. Present only when the service uses horizontal autoscaling. type: integer minimum: 1 maximum: 20 example: 5 autoscalingMode: description: Configured autoscaling mode. "vertical" 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. This is the baseline configuration; the mode currently applied (which may differ while a schedule entry is active) is currentScaling.effectiveAutoscalingMode. type: string enum: - vertical - horizontal example: vertical replicaMemoryGb: description: Fixed memory per replica in Gb for horizontal autoscaling. Present only when the service uses horizontal autoscaling. Must be a multiple of 4, at least 8 Gb, and at most 120 Gb for non paid services or 356 Gb for paid services. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 32 idleScaling: description: When set to true the service is allowed to scale down to zero when idle. True by default. type: boolean idleTimeoutMinutes: description: Set minimum idling timeout (in minutes). Must be >= 5 minutes. type: number ipAccessList: type: array description: List of IP addresses allowed to access the service items: $ref: '#/components/schemas/IpAccessListEntry' createdAt: description: Service creation timestamp. ISO-8601. type: string format: date-time encryptionKey: description: Optional customer provided disk encryption key type: string encryptionAssumedRoleIdentifier: description: Optional role to use for disk encryption type: string iamRole: description: IAM role used for accessing objects in s3 type: string privateEndpointIds: type: array description: List of private endpoints items: type: string availablePrivateEndpointIds: type: array description: List of available private endpoints ids that can be attached to the service items: type: string dataWarehouseId: description: Data warehouse containing this service type: string isPrimary: description: True if this service is the primary service in the data warehouse type: boolean isReadonly: description: True if this service is read-only. It can only be read-only if a dataWarehouseId is provided. type: boolean releaseChannel: description: 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. type: string enum: - slow - default - fast byocId: description: '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.' type: string hasTransparentDataEncryption: description: 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. type: boolean profile: description: 'Custom instance profile. Only available for ENTERPRISE and BYOC organization tiers. Standard values: ''v1-default'', ''v1-highmem-xs'', ''v1-highmem-s'', ''v1-highmem-m'', ''v1-highmem-l'', ''v1-highmem-xl''. 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. Use the serviceProfiles endpoint to list the profiles available to the organization.' type: string transparentDataEncryptionKeyId: description: The ID of the Transparent Data Encryption key used for the service. This is only available if hasTransparentDataEncryption is true. type: string encryptionRoleId: description: The ID of the IAM role used for encryption. This is only available if hasTransparentDataEncryption is true. type: string complianceType: description: Type of regulatory compliance for service. type: string enum: - hipaa - pci tags: type: array description: Tags associated with the service. items: $ref: '#/components/schemas/ResourceTagsV1' maxItems: 50 enableCoreDumps: description: True if the service's underline infra is enabled for collecting core dumps. This is an experimental feature type: boolean scalingSchedule: $ref: '#/components/schemas/ScalingSchedule' currentScaling: $ref: '#/components/schemas/CurrentScaling' required: - autoscalingMode - currentScaling ResourceTagsV1: type: object properties: key: type: string description: Tag key. Must be alphanumeric with dashes, underscores and dots. minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9._-]+$ value: type: string description: Tag value. Must be alphanumeric with dashes, underscores and dots. maxLength: 256 pattern: ^[a-zA-Z0-9._-]+$ required: - key example: key: Environment value: staging ScalingScheduleEntryRequest: properties: name: description: Human-readable label for this schedule entry. type: string example: Business hours weekdays: type: array description: Days of the week this entry applies to. 0 = Sunday, 1 = Monday, …, 6 = Saturday. items: type: integer example: - 1 - 2 - 3 - 4 - 5 minItems: 1 startHourUtc: description: UTC hour (0–23) when this entry becomes active (inclusive). type: integer minimum: 0 maximum: 23 example: 9 endHourUtc: description: UTC hour (1–24) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight. type: integer minimum: 1 maximum: 24 example: 17 autoscalingMode: description: Autoscaling mode for this entry. "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. type: string enum: - vertical - horizontal example: vertical minReplicaMemoryGb: description: Minimum memory per replica (Gb). Optional for vertical entries — provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to maxReplicaMemoryGb — memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 16 maxReplicaMemoryGb: description: Maximum memory per replica (Gb). Optional for vertical entries — provide both bounds for a memory range, or omit both to inherit memory from the base scaling config. Required for horizontal (both bounds, equal to minReplicaMemoryGb — memory is fixed while the replica count scales). The upper bound is tier-dependent (lower for non-paid organizations) and enforced when the entry is applied. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 16 numReplicas: description: Fixed replica count for a vertical entry (autoscalingMode "vertical" or omitted). Mutually exclusive with minReplicas/maxReplicas. The per-service replica maximum is variable (tier-dependent, configurable per service) and enforced when the entry is applied, not at request time. type: integer minimum: 1 example: 3 minReplicas: description: Minimum number of replicas. A minReplicas/maxReplicas band scales the replica count in a horizontal entry (autoscalingMode "horizontal"); when autoscalingMode is omitted or "vertical", an equal band (minReplicas === maxReplicas) is instead an accepted vertical fixed count and needs no horizontal entitlement. Must be provided together with maxReplicas. The per-service replica maximum is variable (tier-dependent, configurable per service) and enforced when the entry is applied, not at request time. type: integer minimum: 1 example: 2 maxReplicas: description: Maximum number of replicas. A minReplicas/maxReplicas band scales the replica count in a horizontal entry (autoscalingMode "horizontal"); when autoscalingMode is omitted or "vertical", an equal band (minReplicas === maxReplicas) is instead an accepted vertical fixed count and needs no horizontal entitlement. Must be provided together with minReplicas. The per-service replica maximum is variable (tier-dependent, configurable per service) and enforced when the entry is applied, not at request time. type: integer minimum: 1 example: 3 idleScaling: description: Whether idle scaling is enabled during this window. type: boolean idleTimeoutMinutes: description: Idle timeout in minutes during this window. type: integer required: - name - weekdays - startHourUtc - endHourUtc ServiceReplicaScalingPatchRequest: properties: minReplicaMemoryGb: description: 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. A range in vertical autoscaling; equal to maxReplicaMemoryGb in horizontal. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 16 maxReplicaMemoryGb: description: 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 356 for paid services. A range in vertical autoscaling; equal to minReplicaMemoryGb in horizontal. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 120 autoscalingMode: description: Target autoscaling mode. Omit to keep the service on its current mode. "vertical" 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). Switching to horizontal requires the feature to be enabled for the organization. type: string enum: - vertical - horizontal example: vertical numReplicas: description: Fixed replica count for vertical autoscaling (autoscalingMode "vertical"). Mutually exclusive with minReplicas/maxReplicas. When switching to vertical (autoscalingMode "vertical") with numReplicas and no memory, the service's stored baseline per-replica memory is kept as the new vertical range. Please contact support to enable adjustment of numReplicas. type: integer minimum: 1 maximum: 20 example: 3 minReplicas: description: 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 service, 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). type: integer minimum: 1 maximum: 20 example: 1 maxReplicas: description: 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 service, 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). type: integer minimum: 1 maximum: 20 example: 5 idleScaling: description: When set to true the service is allowed to scale down to zero when idle. True by default. type: boolean idleTimeoutMinutes: description: Set minimum idling timeout (in minutes). Must be >= 5 minutes. type: number CurrentScaling: properties: effectiveAutoscalingMode: description: Autoscaling mode currently in effect on the running service. May diverge from the configured baseline mode while a schedule entry is active. type: string enum: - vertical - horizontal effectiveMinReplicaMemoryGb: description: Minimum memory per replica (Gb) currently applied to the running service. May diverge from the top-level `minReplicaMemoryGb` baseline while a schedule entry is active. type: number effectiveMaxReplicaMemoryGb: description: 'Maximum memory per replica (Gb) currently applied to the running service. May diverge from the top-level `maxReplicaMemoryGb` baseline while a schedule entry is active. Reflects the stored value: normally equal to `effectiveMinReplicaMemoryGb` in horizontal mode, but a legacy service stored with an unequal memory range reports the stored bounds as-is.' type: number effectiveMinReplicas: description: 'Minimum number of replicas currently applied to the running service. May diverge from the baseline while a schedule entry is active. Reflects the stored value: normally equal to `effectiveMaxReplicas` in vertical mode (a fixed replica count), but a legacy service stored with an unequal replica range reports the stored bounds as-is.' type: integer effectiveMaxReplicas: description: Maximum number of replicas currently applied to the running service. May diverge from the baseline while a schedule entry is active. type: integer effectiveIdleScaling: description: Whether idle scaling is currently in effect on the service. May diverge from the top-level `idleScaling` baseline while a schedule entry is active. type: boolean effectiveIdleTimeoutMinutes: description: Idle timeout in minutes currently in effect on the service. May diverge from the top-level `idleTimeoutMinutes` baseline while a schedule entry is active. type: integer activeEntryId: description: ID of the schedule entry whose values are currently applied to the service. Absent when no entry is active. type: string format: uuid ServiceProfile: properties: profile: description: Profile name to pass as `profile` when creating a service (e.g. 'v1-standard-byoc-4'). type: string cpuCores: description: Number of vCPUs per replica. type: number memoryGi: description: Memory per replica in GiB. When creating a BYOC service with this profile, minReplicaMemoryGb and maxReplicaMemoryGb must both equal this value. type: number ScalingScheduleBaseConfig: properties: autoscalingMode: description: Autoscaling mode applied when no schedule entry is active. "vertical" runs a fixed replica count while memory scales; "horizontal" scales the replica count at a fixed per-replica memory. type: string enum: - vertical - horizontal minReplicaMemoryGb: description: Minimum memory per replica (Gb) when no schedule entry is active. Absent for services that do not autoscale memory. type: number maxReplicaMemoryGb: description: Maximum memory per replica (Gb) when no schedule entry is active. Absent for services that do not autoscale memory. type: number minReplicas: description: Minimum number of replicas when no schedule entry is active. type: integer maxReplicas: description: Maximum number of replicas when no schedule entry is active. type: integer idleScaling: description: Whether idle scaling is enabled when no schedule entry is active. type: boolean idleTimeoutMinutes: description: Idle timeout in minutes when no schedule entry is active. type: integer ServiceEndpoint: properties: protocol: description: 'Endpoint protocol: ''https'', ''nativesecure'', ''mysql''.' type: string enum: - https - nativesecure - mysql example: mysql host: description: Service host name type: string port: description: Numeric port type: number username: description: Optional username for the endpoint type: - string - 'null' ServiceClickhouseSettingsPatchRequest: properties: settings: description: 'JSON object of setting names to values. Example: {"compatibility": "24.8"}' type: string example: '{"compatibility": "24.8"}' required: - settings ServiceClickhouseSetting: properties: name: description: Name of the setting. type: string example: compatibility value: description: Current value of the setting. Returned as a string for all setting types. type: string example: '24.8' ServicePasswordPatchRequest: properties: newPasswordHash: description: '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' type: string newDoubleSha1Hash: description: '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 ''-''' type: string ServicPrivateEndpointePostRequest: properties: id: description: Private endpoint identifier type: string description: description: Description of private endpoint type: string ServiceClickhouseSettingsList: properties: settings: type: array description: List of ClickHouse settings with their current values. items: $ref: '#/components/schemas/ServiceClickhouseSetting' ServicePostRequest: properties: name: description: Name of the service. Alphanumerical string with whitespaces up to 50 characters. type: string maxLength: 50 minLength: 1 provider: description: Cloud provider type: string enum: - aws - gcp - azure region: description: Service region. type: string enum: - 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: description: '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' type: 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 deprecated: true ipAccessList: type: array description: List of IP addresses allowed to access the service items: $ref: '#/components/schemas/IpAccessListEntry' minTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 48 deprecated: true maxTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 360 deprecated: true autoscalingMode: description: 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. type: string enum: - vertical - horizontal example: vertical minReplicaMemoryGb: description: 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. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 16 maxReplicaMemoryGb: description: '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. ' type: number minimum: 8 maximum: 356 multipleOf: 4 example: 120 numReplicas: description: Fixed replica count for vertical autoscaling (autoscalingMode "vertical" or omitted). Mutually exclusive with minReplicas/maxReplicas. type: integer minimum: 1 maximum: 20 example: 3 minReplicas: description: 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). type: integer minimum: 1 maximum: 20 example: 1 maxReplicas: description: 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). type: integer minimum: 1 maximum: 20 example: 5 idleScaling: description: When set to true the service is allowed to scale down to zero when idle. True by default. type: boolean idleTimeoutMinutes: description: Set minimum idling timeout (in minutes). Must be >= 5 minutes. type: number isReadonly: description: True if this service is read-only. It can only be read-only if a dataWarehouseId is provided. type: boolean dataWarehouseId: description: Data warehouse containing this service type: string backupId: description: 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. type: string format: uuid encryptionKey: description: Optional customer provided disk encryption key type: string encryptionAssumedRoleIdentifier: description: Optional role to use for disk encryption type: string privateEndpointIds: type: array description: 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. items: type: string deprecated: true privatePreviewTermsChecked: description: 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 type: boolean releaseChannel: description: 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. type: string enum: - slow - default - fast byocId: description: '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.' type: string hasTransparentDataEncryption: description: 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. type: boolean endpoints: type: array description: List of service endpoints to enable or disable items: $ref: '#/components/schemas/ServiceEndpointChange' profile: description: 'Custom instance profile. Only available for ENTERPRISE and BYOC organization tiers. Standard values: ''v1-default'', ''v1-highmem-xs'', ''v1-highmem-s'', ''v1-highmem-m'', ''v1-highmem-l'', ''v1-highmem-xl''. 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. Use the serviceProfiles endpoint to list the profiles available to the organization.' type: string complianceType: description: Type of regulatory compliance for service. type: string enum: - hipaa - pci tags: type: array description: Tags associated with the service. items: $ref: '#/components/schemas/ResourceTagsV1' maxItems: 50 enableCoreDumps: description: Enables the underlying infra for collecting core dumps. Default is enabled. type: boolean ScalingSchedulePostRequest: properties: entries: type: array description: List of schedule entries. Pass an empty array to clear the schedule. items: $ref: '#/components/schemas/ScalingScheduleEntryRequest' required: - entries ServicePatchRequest: properties: name: description: Name of the service. Alphanumerical string with whitespaces up to 50 characters. type: string maxLength: 50 minLength: 1 ipAccessList: $ref: '#/components/schemas/IpAccessListPatch' privateEndpointIds: $ref: '#/components/schemas/InstancePrivateEndpointsPatch' releaseChannel: description: 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. type: string enum: - slow - default - fast endpoints: type: array description: List of service endpoints to change items: $ref: '#/components/schemas/ServiceEndpointChange' transparentDataEncryptionKeyId: description: The id of the key to rotate type: string tags: $ref: '#/components/schemas/InstanceTagsPatch' enableCoreDumps: description: If true, the underlying infra is enabled for collecting core dumps. type: boolean ServiceEndpointChange: properties: protocol: description: Endpoint protocol type: string enum: - mysql example: mysql enabled: description: Enable or disable the endpoint type: boolean ServiceClickhouseSettingsPatchResponse: properties: settings: description: 'JSON object of setting names to their applied values. Example: {"compatibility": "24.8"}' type: string example: '{"compatibility": "24.8"}' warnings: type: array description: Warnings for settings that may have disruptive effects. items: $ref: '#/components/schemas/ServiceClickhouseSettingWarning' InstancePrivateEndpoint: properties: id: description: Private endpoint identifier type: string description: description: Description of private endpoint type: string cloudProvider: description: Cloud provider in which the private endpoint is lcoated type: string enum: - gcp - aws - azure region: description: Region in which the private endpoint is located type: string enum: - 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 ServiceScalingPatchResponse: properties: id: description: Unique service ID. type: string format: uuid name: description: Name of the service. Alphanumerical string with whitespaces up to 50 characters. type: string maxLength: 50 minLength: 1 provider: description: Cloud provider type: string enum: - aws - gcp - azure region: description: Service region. type: string enum: - 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 state: description: Current state of the service. type: string enum: - starting - stopping - terminating - softdeleting - awaking - partially_running - provisioning - running - stopped - terminated - softdeleted - degraded - failed - idle clickhouseVersion: description: ClickHouse version of the service. type: string endpoints: type: array description: List of all service endpoints. items: $ref: '#/components/schemas/ServiceEndpoint' tier: description: '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' type: 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 deprecated: true minTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 48 deprecated: true maxTotalMemoryGb: description: 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). type: number minimum: 24 maximum: 1068 multipleOf: 12 example: 360 deprecated: true minReplicaMemoryGb: description: 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. A range in vertical autoscaling; equal to maxReplicaMemoryGb in horizontal (memory is fixed while the replica count scales). type: number minimum: 8 maximum: 356 multipleOf: 4 example: 16 maxReplicaMemoryGb: description: 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 356 for paid services. A range in vertical autoscaling; equal to minReplicaMemoryGb in horizontal (memory is fixed while the replica count scales). type: number minimum: 8 maximum: 356 multipleOf: 4 example: 120 numReplicas: description: 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. Present only when the service uses vertical autoscaling. For horizontal autoscaling, use minReplicas and maxReplicas instead. type: integer minimum: 1 maximum: 20 example: 3 minReplicas: description: Minimum number of replicas for horizontal autoscaling. Present only when the service uses horizontal autoscaling. type: integer minimum: 1 maximum: 20 example: 1 maxReplicas: description: Maximum number of replicas for horizontal autoscaling. Present only when the service uses horizontal autoscaling. type: integer minimum: 1 maximum: 20 example: 5 autoscalingMode: description: Configured autoscaling mode. "vertical" 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. This is the baseline configuration; the mode currently applied (which may differ while a schedule entry is active) is currentScaling.effectiveAutoscalingMode. type: string enum: - vertical - horizontal example: vertical replicaMemoryGb: description: Fixed memory per replica in Gb for horizontal autoscaling. Present only when the service uses horizontal autoscaling. Must be a multiple of 4, at least 8 Gb, and at most 120 Gb for non paid services or 356 Gb for paid services. type: number minimum: 8 maximum: 356 multipleOf: 4 example: 32 idleScaling: description: When set to true the service is allowed to scale down to zero when idle. True by default. type: boolean idleTimeoutMinutes: description: Set minimum idling timeout (in minutes). Must be >= 5 minutes. type: number ipAccessList: type: array description: List of IP addresses allowed to access the service items: $ref: '#/components/schemas/IpAccessListEntry' createdAt: description: Service creation timestamp. ISO-8601. type: string format: date-time encryptionKey: description: Optional customer provided disk encryption key type: string encryptionAssumedRoleIdentifier: description: Optional role to use for disk encryption type: string iamRole: description: IAM role used for accessing objects in s3 type: string privateEndpointIds: type: array description: List of private endpoints items: type: string availablePrivateEndpointIds: type: array description: List of available private endpoints ids that can be attached to the service items: type: string dataWarehouseId: description: Data warehouse containing this service type: string isPrimary: description: True if this service is the primary service in the data warehouse type: boolean isReadonly: description: True if this service is read-only. It can only be read-only if a dataWarehouseId is provided. type: boolean releaseChannel: description: 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. type: string enum: - slow - default - fast byocId: description: '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.' type: string hasTransparentDataEncryption: description: 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. type: boolean profile: description: 'Custom instance profile. Only available for ENTERPRISE and BYOC organization tiers. Standard values: ''v1-default'', ''v1-highmem-xs'', ''v1-highmem-s'', ''v1-highmem-m'', ''v1-highmem-l'', ''v1-highmem-xl''. 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. Use the serviceProfiles endpoint to list the profiles available to the organization.' type: string transparentDataEncryptionKeyId: description: The ID of the Transparent Data Encryption key used for the service. This is only available if hasTransparentDataEncryption is true. type: string encryptionRoleId: description: The ID of the IAM role used for encryption. This is only available if hasTransparentDataEncryption is true. type: string complianceType: description: Type of regulatory compliance for service. type: string enum: - hipaa - pci tags: type: array description: Tags associated with the service. items: $ref: '#/components/schemas/ResourceTagsV1' maxItems: 50 enableCoreDumps: description: True if the service's underline infra is enabled for collecting core dumps. This is an experimental feature type: boolean scalingSchedule: $ref: '#/components/schemas/ScalingSchedule' currentScaling: $ref: '#/components/schemas/CurrentScaling' required: - autoscalingMode - currentScaling PrivateEndpointConfig: properties: endpointServiceId: description: Unique identifier of the interface endpoint you created in your VPC with the AWS(Service Name), GCP(Target Service) or AZURE (Private Link Service) resource type: string privateDnsHostname: description: Private DNS Hostname of the VPC you created type: string ScalingScheduleEntry: properties: id: description: Unique identifier for this schedule entry. type: string format: uuid name: description: Human-readable label for this schedule entry. type: string weekdays: type: array description: Days of the week this entry applies to. 0 = Sunday, 1 = Monday, …, 6 = Saturday. items: type: integer minItems: 1 startHourUtc: description: UTC hour (0–23) when this entry becomes active (inclusive). type: integer minimum: 0 maximum: 23 endHourUtc: description: UTC hour (1–24) when this entry deactivates (exclusive). Must differ from startHourUtc. Set to 24 to end at midnight. Values less than startHourUtc create an overnight window spanning midnight. type: integer minimum: 1 maximum: 24 autoscalingMode: description: Autoscaling mode for this entry. "vertical" runs a fixed replica count while memory scales; "horizontal" scales the replica count at a fixed per-replica memory. Defaults to "vertical" for entries persisted before the mode was exposed. type: string enum: - vertical - horizontal minReplicaMemoryGb: description: Minimum memory per replica (Gb) during this window. A range in vertical; in horizontal it equals maxReplicaMemoryGb (memory is fixed while the replica count scales). type: number maxReplicaMemoryGb: description: Maximum memory per replica (Gb) during this window. A range in vertical; in horizontal it equals minReplicaMemoryGb (memory is fixed while the replica count scales). type: number minReplicas: description: Minimum number of replicas during this window. For a horizontal entry the replica count scales between minReplicas and maxReplicas; for a vertical entry minReplicas and maxReplicas are equal and report the fixed replica count (both omitted when the entry stored no count). type: integer maxReplicas: description: Maximum number of replicas during this window. For a horizontal entry the replica count scales between minReplicas and maxReplicas; for a vertical entry minReplicas and maxReplicas are equal and report the fixed replica count (both omitted when the entry stored no count). type: integer idleScaling: description: Whether idle scaling is enabled during this window. type: boolean idleTimeoutMinutes: description: Idle timeout in minutes during this window. type: integer isActiveNow: description: Whether this entry is currently active. Scheduled times are indicative — actions are applied on a best-effort basis and may be delayed by a few minutes. type: boolean required: - id - name - weekdays - startHourUtc - endHourUtc - autoscalingMode - isActiveNow ServiceClickhouseSettingSchemaEntry: properties: name: description: Name of the setting. type: string example: compatibility type: description: Data type of the setting value. type: string example: string description: description: Description of the setting. type: string example: ClickHouse version compatibility setting. enum: type: array description: List of allowed values, if the setting is an enum. items: type: integer example: - 0 - 1 warning: description: Warning message about potential disruptive effects of changing this setting. type: string example: Changing this setting without comprehensive testing can cause instability. deprecationNotice: description: Deprecation notice, if applicable. type: string example: This setting may become obsolete with Cloud v2 stateless workers. example: description: Example value for the setting. type: string example: '24.8' securitySchemes: basicAuth: type: http scheme: basic description: 'Use key ID and key secret obtained in ClickHouse Cloud console: https://clickhouse.com/docs/cloud/manage/openapi' x-tagGroups: - name: Organization tags: - Organization - Billing - User management - Role Management - UDF - name: Service tags: - Service - Backup - name: API keys tags: - API keys - name: Prometheus tags: - Prometheus - name: ClickPipes tags: - ClickPipes - name: ClickStack tags: - ClickStack - name: Postgres tags: - Postgres