# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenAPI spec for ClickHouse Cloud Service API
  version: 1.0.0
extends: openapi/clickhouse-service-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 26
- target: $.paths['/v1/organizations/{organizationId}/serviceProfiles'].get
  update:
    x-apievangelist-phrasing:
      intent: List instance profiles available in a region
      effect: read
      questions:
      - Which custom instance profiles can I use for a new service in a region?
      - What profiles are configured for my BYOC infrastructure?
      instructions:
      - text: List service profiles for org {org} in region {region_id}.
        slots:
          org: path.organizationId
          region_id: query.region_id
      - text: Show the instance profiles on BYOC infrastructure {byoc_id} in region {region_id} for organization {org}.
        slots:
          byoc_id: query.byoc_id
          region_id: query.region_id
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickHouse services in the organization
      effect: read
      questions:
      - What ClickHouse services are running in my organization?
      - Can I narrow the list of services with a filter?
      instructions:
      - text: List all ClickHouse services in org {org}.
        slots:
          org: path.organizationId
      - text: Show services in organization {org} matching filter {filter}.
        slots:
          org: path.organizationId
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new ClickHouse service
      effect: write
      questions:
      - How do I spin up a new ClickHouse Cloud service?
      - Can I create a service from an existing backup?
      - Can I make a read-only service that shares a data warehouse with another one?
      instructions:
      - text: Create a ClickHouse service named {name} on {provider} in region {region} in org {org}.
        slots:
          name: requestBody.name
          provider: requestBody.provider
          region: requestBody.region
          org: path.organizationId
      - text: Launch a new service {name} in organization {org} restored from backup {backupId}.
        slots:
          name: requestBody.name
          org: path.organizationId
          backupId: requestBody.backupId
      - text: Create read-only service {name} in org {org} attached to data warehouse {dataWarehouseId}.
        slots:
          name: requestBody.name
          org: path.organizationId
          dataWarehouseId: requestBody.dataWarehouseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a ClickHouse service's details
      effect: read
      questions:
      - What state is my ClickHouse service in right now?
      - Which endpoints and region does a particular service use?
      instructions:
      - text: Show ClickHouse service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Get the state and endpoints of service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a stopped ClickHouse service
      effect: destructive
      questions:
      - How do I permanently delete a ClickHouse service?
      - Does a service have to be stopped before I can delete it?
      instructions:
      - text: Delete ClickHouse service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Permanently remove stopped service {service} from organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a service or change its IP access list
      effect: write
      questions:
      - How do I rename a ClickHouse service?
      - Can I restrict which IP addresses can connect to my service?
      - How do I move a service to a different release channel?
      instructions:
      - text: Rename service {service} in org {org} to {name}.
        slots:
          service: path.serviceId
          org: path.organizationId
          name: requestBody.name
      - text: Set the IP access list of service {service} in organization {org} to {ipAccessList}.
        slots:
          service: path.serviceId
          org: path.organizationId
          ipAccessList: requestBody.ipAccessList
      - text: Switch service {service} in org {org} to release channel {releaseChannel}.
        slots:
          service: path.serviceId
          org: path.organizationId
          releaseChannel: requestBody.releaseChannel
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/privateEndpointConfig'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the info needed to set up a private endpoint
      effect: read
      questions:
      - What endpoint service name do I need to set up PrivateLink to my ClickHouse service?
      - Where do I find the private DNS host for a service's private endpoint?
      instructions:
      - text: Get the private endpoint configuration for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Show what I need to connect privately to service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service's query-over-API endpoint config
      effect: read
      questions:
      - Is the query API endpoint enabled on my ClickHouse service?
      - Which roles and allowed origins are set on a service's query endpoint?
      instructions:
      - text: Show the service query endpoint for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Check which API keys can run queries over HTTP against service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint'].post
  update:
    x-apievangelist-phrasing:
      intent: Enable or configure the query-over-API endpoint
      effect: write
      questions:
      - How do I let an app run SQL queries against my service over an HTTP API?
      - Can I restrict the query endpoint to certain API keys and browser origins?
      instructions:
      - text: Enable the query endpoint on service {service} in org {org} for API keys {openApiKeys}.
        slots:
          service: path.serviceId
          org: path.organizationId
          openApiKeys: requestBody.openApiKeys
      - text: Configure the query endpoint of service {service} in organization {org} with roles {roles} and allowed origins {allowedOrigins}.
        slots:
          service: path.serviceId
          org: path.organizationId
          roles: requestBody.roles
          allowedOrigins: requestBody.allowedOrigins
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/serviceQueryEndpoint'].delete
  update:
    x-apievangelist-phrasing:
      intent: Disable the query-over-API endpoint
      effect: destructive
      questions:
      - How do I turn off running queries over HTTP against my service?
      - Can I remove the query API endpoint from a service?
      instructions:
      - text: Delete the service query endpoint on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Disable query-over-API access for service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/state'].patch
  update:
    x-apievangelist-phrasing:
      intent: Start, stop or wake a ClickHouse service
      effect: write
      questions:
      - How do I stop a ClickHouse service to save money overnight?
      - Can I wake an idle service without manage permissions?
      - Does the awake command start a service that was stopped?
      instructions:
      - text: Stop ClickHouse service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Send state command {command} to service {service} in organization {org}.
        slots:
          command: requestBody.command
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/scaling'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set total memory limits and idle scaling
      effect: write
      questions:
      - How do I set the minimum and maximum total memory for a production service?
      - Can I make my service idle after a number of minutes of inactivity?
      instructions:
      - text: Scale service {service} in org {org} between {minTotalMemoryGb} and {maxTotalMemoryGb} GB total memory.
        slots:
          service: path.serviceId
          org: path.organizationId
          minTotalMemoryGb: requestBody.minTotalMemoryGb
          maxTotalMemoryGb: requestBody.maxTotalMemoryGb
      - text: Let service {service} in organization {org} go idle after {idleTimeoutMinutes} minutes using total-memory scaling settings.
        slots:
          service: path.serviceId
          org: path.organizationId
          idleTimeoutMinutes: requestBody.idleTimeoutMinutes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/replicaScaling'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set per-replica memory and replica autoscaling
      effect: write
      questions:
      - How do I set per-replica memory limits for vertical autoscaling?
      - Can I autoscale horizontally between a minimum and maximum number of replicas?
      instructions:
      - text: Set per-replica memory on service {service} in org {org} between {minReplicaMemoryGb} and {maxReplicaMemoryGb} GB.
        slots:
          service: path.serviceId
          org: path.organizationId
          minReplicaMemoryGb: requestBody.minReplicaMemoryGb
          maxReplicaMemoryGb: requestBody.maxReplicaMemoryGb
      - text: Autoscale service {service} in organization {org} in mode {autoscalingMode} from {minReplicas} to {maxReplicas} replicas.
        slots:
          service: path.serviceId
          org: path.organizationId
          autoscalingMode: requestBody.autoscalingMode
          minReplicas: requestBody.minReplicas
          maxReplicas: requestBody.maxReplicas
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/password'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a ClickHouse service's password
      effect: write
      questions:
      - How do I reset the default user password on my ClickHouse service?
      - Can I set the service password by sending a hash instead of plain text?
      instructions:
      - text: Set a new password on service {service} in org {org} using hash {newPasswordHash}.
        slots:
          service: path.serviceId
          org: path.organizationId
          newPasswordHash: requestBody.newPasswordHash
      - text: Reset the ClickHouse service password for {service} in organization {org} with double SHA1 hash {newDoubleSha1Hash}.
        slots:
          service: path.serviceId
          org: path.organizationId
          newDoubleSha1Hash: requestBody.newDoubleSha1Hash
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/privateEndpoint'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a private endpoint to a service
      effect: write
      questions:
      - How do I register my cloud private endpoint with a ClickHouse service?
      - Can I add a description to a private endpoint when I create it?
      instructions:
      - text: Create private endpoint {endpointId} for service {service} in org {org}.
        slots:
          endpointId: requestBody.id
          service: path.serviceId
          org: path.organizationId
      - text: Associate private endpoint {endpointId} described as {description} with service {service} in organization {org}.
        slots:
          endpointId: requestBody.id
          description: requestBody.description
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/scalingSchedule'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service's scheduled autoscaling
      effect: read
      questions:
      - Does my service have a time-based scaling schedule?
      - What scaling changes are scheduled for this service?
      instructions:
      - text: Show the autoscaling schedule for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Get the scheduled scaling entries on service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/scalingSchedule'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a service's scheduled autoscaling
      effect: write
      questions:
      - How do I scale a service up during business hours and down at night on a schedule?
      - Can I clear a scaling schedule by sending no entries?
      instructions:
      - text: Set the autoscaling schedule for service {service} in org {org} to {entries}.
        slots:
          service: path.serviceId
          org: path.organizationId
          entries: requestBody.entries
      - text: Replace the scheduled scaling on service {service} in organization {org} with entries {entries}.
        slots:
          service: path.serviceId
          org: path.organizationId
          entries: requestBody.entries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/scalingSchedule'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a service's scheduled autoscaling
      effect: destructive
      questions:
      - How do I delete the scaling schedule on a service?
      - What happens to the current scaling when I remove an active schedule?
      instructions:
      - text: Delete the scaling schedule for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Remove scheduled autoscaling from service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/upgradeWindow'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service's upgrade window
      effect: read
      questions:
      - When is my ClickHouse service scheduled to receive upgrades?
      - Which day and hour is the upgrade window set to?
      instructions:
      - text: Show the upgrade window for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Get the configured maintenance upgrade slot of service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/upgradeWindow'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a service's upgrade window
      effect: write
      questions:
      - How do I make upgrades happen on the weekend instead of during business hours?
      - Which start hours are allowed for an upgrade window, and how long does it last?
      instructions:
      - text: Set the upgrade window of service {service} in org {org} to weekday {weekday} starting at {startHourUtc} UTC.
        slots:
          service: path.serviceId
          org: path.organizationId
          weekday: requestBody.weekday
          startHourUtc: requestBody.startHourUtc
      - text: Schedule upgrades for primary service {service} in organization {org} on day {weekday} at hour {startHourUtc} UTC.
        slots:
          service: path.serviceId
          org: path.organizationId
          weekday: requestBody.weekday
          startHourUtc: requestBody.startHourUtc
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/upgradeWindow'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a service's upgrade window
      effect: destructive
      questions:
      - How do I go back to the default upgrade scheduling for a service?
      - Can I delete a custom upgrade window?
      instructions:
      - text: Delete the upgrade window on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Restore default upgrade scheduling for service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickHouse settings explicitly set on a service
      effect: read
      questions:
      - Which ClickHouse server settings have been customized on my service?
      - What settings did we override from the platform defaults?
      instructions:
      - text: List the configured ClickHouse settings for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Show every setting overridden on service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change ClickHouse settings on a service
      effect: write
      questions:
      - How do I change a ClickHouse server setting on my service?
      - Can I update several ClickHouse settings in one call?
      instructions:
      - text: Apply ClickHouse settings {settings} to service {service} in org {org}.
        slots:
          settings: requestBody.settings
          service: path.serviceId
          org: path.organizationId
      - text: Update the server settings on service {service} in organization {org} to {settings}.
        slots:
          service: path.serviceId
          org: path.organizationId
          settings: requestBody.settings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings/schema'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the schema of configurable ClickHouse settings
      effect: read
      questions:
      - Which ClickHouse settings am I allowed to configure, and what values are valid?
      - Where can I see types and descriptions for every tunable setting?
      instructions:
      - text: Get the ClickHouse settings schema for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Show all configurable settings and their valid values for service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings/{settingName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ClickHouse setting's value
      effect: read
      questions:
      - What is the current value of a specific ClickHouse setting on my service?
      - Is one particular setting still at its default?
      instructions:
      - text: Get ClickHouse setting {settingName} on service {service} in org {org}.
        slots:
          settingName: path.settingName
          service: path.serviceId
          org: path.organizationId
      - text: Show the current value of {settingName} for service {service} in organization {org}.
        slots:
          settingName: path.settingName
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickhouseSettings/{settingName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reset a ClickHouse setting to its default
      effect: destructive
      questions:
      - How do I undo a custom ClickHouse setting and return it to the platform default?
      - Can I remove one override without touching my other settings?
      instructions:
      - text: Reset ClickHouse setting {settingName} on service {service} in org {org} to default.
        slots:
          settingName: path.settingName
          service: path.serviceId
          org: path.organizationId
      - text: Remove the override for {settingName} from service {service} in organization {org}.
        slots:
          settingName: path.settingName
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'