# 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 Backup API
  version: 1.0.0
extends: openapi/clickhouse-backup-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: 8
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/backups'].get
  update:
    x-apievangelist-phrasing:
      intent: List a service's backups
      effect: read
      questions:
      - What backups exist for my ClickHouse service, newest first?
      - When was the most recent backup of this service taken?
      instructions:
      - text: List all backups for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Show the latest backups taken 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}/backups/{backupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of one backup
      effect: read
      questions:
      - What are the details of one particular backup?
      - Did a specific backup of my service finish successfully?
      instructions:
      - text: Show backup {backupId} of service {service} in org {org}.
        slots:
          backupId: path.backupId
          service: path.serviceId
          org: path.organizationId
      - text: Check whether backup {backupId} for service {service} in organization {org} completed.
        slots:
          backupId: path.backupId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/backupConfiguration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service's backup schedule and retention
      effect: read
      questions:
      - How often is my service backed up and how long are backups kept?
      - What start time is configured for this service's backups?
      instructions:
      - text: Show the backup configuration for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Tell me the backup period and retention settings 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}/backupConfiguration'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a service's backup schedule and retention
      effect: write
      questions:
      - Can I take backups every 12 hours and keep them longer?
      - How do I reset the backup schedule back to its defaults?
      instructions:
      - text: Back up service {service} in org {org} every {backupPeriodInHours} hours.
        slots:
          service: path.serviceId
          org: path.organizationId
          backupPeriodInHours: requestBody.backupPeriodInHours
      - text: Keep backups of service {service} in organization {org} for {backupRetentionPeriodInHours} hours, starting at {backupStartTime}.
        slots:
          service: path.serviceId
          org: path.organizationId
          backupRetentionPeriodInHours: requestBody.backupRetentionPeriodInHours
          backupStartTime: requestBody.backupStartTime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/backupBucket'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service's custom backup bucket
      effect: read
      questions:
      - Which external bucket are my service's backups written to?
      - Is a bring-your-own backup bucket configured for this service?
      instructions:
      - text: Show the backup bucket configured for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Check whether service {service} in organization {org} sends backups to its own bucket.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/backupBucket'].post
  update:
    x-apievangelist-phrasing:
      intent: Set up a custom backup bucket for a service
      effect: write
      questions:
      - How do I send my service's backups to a bucket in my own cloud account?
      - What role does my API key need to add a backup bucket?
      instructions:
      - text: Create a backup bucket for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Configure service {service} in organization {org} to write backups to my own bucket.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/backupBucket'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a service's custom backup bucket
      effect: destructive
      questions:
      - How do I stop using my own bucket for a service's backups?
      - Can I detach the external backup bucket from a service?
      instructions:
      - text: Delete the backup bucket configured on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Remove the custom backup bucket 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}/backupBucket'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a service's custom backup bucket
      effect: write
      questions:
      - How do I rotate the credentials on my existing backup bucket?
      - Do I have to resend the bucket secrets every time I change the backup bucket?
      instructions:
      - text: Update the existing backup bucket settings for service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Rotate the secrets on the backup bucket already attached to service {service} in organization {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'