# 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 Click Stack API
  version: 1.0.0
extends: openapi/clickhouse-clickstack-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: 30
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickStack dashboards
      effect: read
      questions:
      - Which observability dashboards exist in ClickStack for my service?
      - Can I see all of my team's ClickStack dashboards?
      instructions:
      - text: List all ClickStack dashboards on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Show every observability dashboard my team has 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}/clickstack/dashboards'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a ClickStack dashboard
      effect: write
      questions:
      - How do I build a new observability dashboard with chart tiles in ClickStack?
      - Can I tag a new dashboard and give it default filters?
      instructions:
      - text: Create a ClickStack dashboard named {name} with tiles {tiles} on service {service} in org {org}.
        slots:
          name: requestBody.name
          tiles: requestBody.tiles
          service: path.serviceId
          org: path.organizationId
      - text: Save a new dashboard {name} tagged {tags} with tiles {tiles} for service {service} in organization {org}.
        slots:
          name: requestBody.name
          tags: requestBody.tags
          tiles: requestBody.tiles
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/{clickStackDashboardId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ClickStack dashboard
      effect: read
      questions:
      - What tiles and filters are on a specific ClickStack dashboard?
      - Can I export the definition of one dashboard?
      instructions:
      - text: Get ClickStack dashboard {dashboard} on service {service} in org {org}.
        slots:
          dashboard: path.clickStackDashboardId
          service: path.serviceId
          org: path.organizationId
      - text: Show the tiles of dashboard {dashboard} for service {service} in organization {org}.
        slots:
          dashboard: path.clickStackDashboardId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/{clickStackDashboardId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing ClickStack dashboard
      effect: write
      questions:
      - How do I change the tiles on a dashboard I already built?
      - Does updating a dashboard protect against someone else editing it at the same time?
      instructions:
      - text: Update dashboard {dashboard} on service {service} in org {org} with name {name} and tiles {tiles}.
        slots:
          dashboard: path.clickStackDashboardId
          service: path.serviceId
          org: path.organizationId
          name: requestBody.name
          tiles: requestBody.tiles
      - text: Replace the tiles on existing dashboard {dashboard} for service {service} in organization {org} with {tiles}, keeping name {name}.
        slots:
          dashboard: path.clickStackDashboardId
          service: path.serviceId
          org: path.organizationId
          tiles: requestBody.tiles
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/{clickStackDashboardId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a ClickStack dashboard
      effect: destructive
      questions:
      - How do I remove a ClickStack dashboard nobody uses anymore?
      - Can I delete an observability dashboard by its ID?
      instructions:
      - text: Delete ClickStack dashboard {dashboard} on service {service} in org {org}.
        slots:
          dashboard: path.clickStackDashboardId
          service: path.serviceId
          org: path.organizationId
      - text: Remove dashboard {dashboard} from service {service} in organization {org}.
        slots:
          dashboard: path.clickStackDashboardId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/dashboards/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a dashboard definition without saving
      effect: read
      questions:
      - Can I check a dashboard definition is valid before applying it from Terraform?
      - Is there a dry run that tests dashboard tiles without saving anything?
      instructions:
      - text: Validate dashboard {name} with tiles {tiles} for service {service} in org {org} without saving it.
        slots:
          name: requestBody.name
          tiles: requestBody.tiles
          service: path.serviceId
          org: path.organizationId
      - text: Dry-run check the tile rules for dashboard config {name} ({tiles}) on service {service} in organization {org}.
        slots:
          name: requestBody.name
          tiles: requestBody.tiles
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/alerts'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickStack alerts
      effect: read
      questions:
      - Which alerts are configured in ClickStack for my team?
      - How many alerts can I fetch per page, and how do I get the rest?
      instructions:
      - text: List ClickStack alerts on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Get {limit} alerts starting at offset {offset} for service {service} in organization {org}.
        slots:
          limit: query.limit
          offset: query.offset
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/alerts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a ClickStack alert
      effect: write
      questions:
      - How do I get alerted when a saved search crosses a threshold?
      - Can I set an alert on a dashboard tile that notifies a webhook channel?
      - Can an alert require several consecutive windows before it fires?
      instructions:
      - text: Create an alert named {name} on saved search {savedSearchId} firing above {threshold} every {interval} for service {service} in org {org}.
        slots:
          name: requestBody.name
          savedSearchId: requestBody.savedSearchId
          threshold: requestBody.threshold
          interval: requestBody.interval
          service: path.serviceId
          org: path.organizationId
      - text: Alert on tile {tileId} of dashboard {dashboardId} via channel {channel} for service {service} in organization {org}.
        slots:
          tileId: requestBody.tileId
          dashboardId: requestBody.dashboardId
          channel: requestBody.channel
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/sources'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickStack data sources
      effect: read
      questions:
      - Which log, trace and metric sources are defined in ClickStack?
      - What data sources can my ClickStack searches and dashboards use?
      instructions:
      - text: List all ClickStack sources on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Show the observability data sources defined 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}/clickstack/sources'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a ClickStack data source
      effect: write
      questions:
      - How do I register a new table as a ClickStack source?
      - What granularity format do materialized views on a new source accept?
      instructions:
      - text: Create a new ClickStack source on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Register a new observability source 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}/clickstack/sources/{clickStackSourceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ClickStack data source
      effect: read
      questions:
      - How is a specific ClickStack source configured?
      - Which table and materialized views does one source point at?
      instructions:
      - text: Get ClickStack source {source} on service {service} in org {org}.
        slots:
          source: path.clickStackSourceId
          service: path.serviceId
          org: path.organizationId
      - text: Show the configuration of source {source} for service {service} in organization {org}.
        slots:
          source: path.clickStackSourceId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/sources/{clickStackSourceId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a ClickStack data source
      effect: write
      questions:
      - Do I have to send the whole source object to change one ClickStack source?
      - How do I update the settings of an existing source?
      instructions:
      - text: Update ClickStack source {source} on service {service} in org {org} with its full new definition.
        slots:
          source: path.clickStackSourceId
          service: path.serviceId
          org: path.organizationId
      - text: Replace the existing source {source} for service {service} in organization {org}.
        slots:
          source: path.clickStackSourceId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/sources/{clickStackSourceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a ClickStack data source
      effect: destructive
      questions:
      - How do I remove a data source from ClickStack?
      - Can I delete a source I registered by mistake?
      instructions:
      - text: Delete ClickStack source {source} on service {service} in org {org}.
        slots:
          source: path.clickStackSourceId
          service: path.serviceId
          org: path.organizationId
      - text: Remove observability source {source} from service {service} in organization {org}.
        slots:
          source: path.clickStackSourceId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/alerts/{clickStackAlertId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ClickStack alert
      effect: read
      questions:
      - What threshold and channel is a specific alert using?
      - Which saved search or tile does one of my alerts watch?
      instructions:
      - text: Get ClickStack alert {alert} on service {service} in org {org}.
        slots:
          alert: path.clickStackAlertId
          service: path.serviceId
          org: path.organizationId
      - text: Show the threshold and schedule of alert {alert} for service {service} in organization {org}.
        slots:
          alert: path.clickStackAlertId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/alerts/{clickStackAlertId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing ClickStack alert
      effect: write
      questions:
      - How do I raise the threshold on an alert that's too noisy?
      - Can I change which channel an existing alert notifies?
      instructions:
      - text: Change the threshold of alert {alert} on service {service} in org {org} to {threshold}.
        slots:
          alert: path.clickStackAlertId
          service: path.serviceId
          org: path.organizationId
          threshold: requestBody.threshold
      - text: Point existing alert {alert} for service {service} in organization {org} at channel {channel} with message {message}.
        slots:
          alert: path.clickStackAlertId
          service: path.serviceId
          org: path.organizationId
          channel: requestBody.channel
          message: requestBody.message
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/alerts/{clickStackAlertId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a ClickStack alert
      effect: destructive
      questions:
      - How do I delete an alert that no longer matters?
      - Can I remove a ClickStack alert by its ID?
      instructions:
      - text: Delete ClickStack alert {alert} on service {service} in org {org}.
        slots:
          alert: path.clickStackAlertId
          service: path.serviceId
          org: path.organizationId
      - text: Remove alert {alert} from service {service} in organization {org}.
        slots:
          alert: path.clickStackAlertId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/webhooks'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickStack notification webhooks
      effect: read
      questions:
      - Which webhooks can my ClickStack alerts send notifications to?
      - How do I page through a long list of ClickStack webhooks?
      instructions:
      - text: List ClickStack webhooks on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Get {limit} webhooks from offset {offset} for service {service} in organization {org}.
        slots:
          limit: query.limit
          offset: query.offset
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/webhooks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a ClickStack notification webhook
      effect: write
      questions:
      - How do I send ClickStack alert notifications to my own URL?
      - Can I add custom headers and a body template to an alert webhook?
      instructions:
      - text: Create a webhook named {name} for {webhookService} posting to {url} on service {service} in org {org}.
        slots:
          name: requestBody.name
          webhookService: requestBody.service
          url: requestBody.url
          service: path.serviceId
          org: path.organizationId
      - text: Add a {webhookService} webhook {name} at {url} with headers {headers} for service {service} in organization {org}.
        slots:
          webhookService: requestBody.service
          name: requestBody.name
          url: requestBody.url
          headers: requestBody.headers
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/webhooks/{clickStackWebhookId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a ClickStack notification webhook
      effect: write
      questions:
      - How do I change the URL an existing alert webhook posts to?
      - Does updating a webhook replace all of its fields?
      instructions:
      - text: Update webhook {webhook} on service {service} in org {org} to post to {url} as {name} via {webhookService}.
        slots:
          webhook: path.clickStackWebhookId
          service: path.serviceId
          org: path.organizationId
          url: requestBody.url
          name: requestBody.name
          webhookService: requestBody.service
      - text: Replace existing webhook {webhook} for service {service} in organization {org} with name {name}, type {webhookService} and URL {url}.
        slots:
          webhook: path.clickStackWebhookId
          service: path.serviceId
          org: path.organizationId
          name: requestBody.name
          webhookService: requestBody.service
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/webhooks/{clickStackWebhookId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a ClickStack notification webhook
      effect: destructive
      questions:
      - Why can't I delete a webhook that alerts still use?
      - How do I remove a notification webhook from ClickStack?
      instructions:
      - text: Delete webhook {webhook} on service {service} in org {org}.
        slots:
          webhook: path.clickStackWebhookId
          service: path.serviceId
          org: path.organizationId
      - text: Remove the unused alert webhook {webhook} from service {service} in organization {org}.
        slots:
          webhook: path.clickStackWebhookId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickStack team roles
      effect: read
      questions:
      - Which predefined and custom roles exist for my ClickStack team?
      - What ClickStack roles can I give teammates?
      instructions:
      - text: List ClickStack roles on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Show the predefined and custom ClickStack team roles 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}/clickstack/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom ClickStack team role
      effect: write
      questions:
      - How do I create a ClickStack role with limited permissions for my observability team?
      - Can a custom ClickStack role have its own description?
      instructions:
      - text: Create a ClickStack role {name} with permissions {permissions} on service {service} in org {org}.
        slots:
          name: requestBody.name
          permissions: requestBody.permissions
          service: path.serviceId
          org: path.organizationId
      - text: Add a custom ClickStack team role {name} described as {description} granting {permissions} for service {service} in organization {org}.
        slots:
          name: requestBody.name
          description: requestBody.description
          permissions: requestBody.permissions
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/roles/{clickStackRoleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ClickStack team role
      effect: read
      questions:
      - What permissions does a specific ClickStack role include?
      - Is a given ClickStack role predefined or custom?
      instructions:
      - text: Get ClickStack role {role} on service {service} in org {org}.
        slots:
          role: path.clickStackRoleId
          service: path.serviceId
          org: path.organizationId
      - text: Show the permissions of ClickStack team role {role} for service {service} in organization {org}.
        slots:
          role: path.clickStackRoleId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/roles/{clickStackRoleId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom ClickStack team role
      effect: write
      questions:
      - How do I change the permissions on a custom ClickStack role?
      - Can predefined ClickStack roles be edited?
      instructions:
      - text: Set the permissions of ClickStack role {role} on service {service} in org {org} to {permissions}.
        slots:
          role: path.clickStackRoleId
          service: path.serviceId
          org: path.organizationId
          permissions: requestBody.permissions
      - text: Rename custom ClickStack role {role} to {name} with permissions {permissions} for service {service} in organization {org}.
        slots:
          role: path.clickStackRoleId
          name: requestBody.name
          permissions: requestBody.permissions
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/roles/{clickStackRoleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom ClickStack team role
      effect: destructive
      questions:
      - Why won't ClickStack let me delete a role that's assigned to users?
      - How do I remove a custom ClickStack role?
      instructions:
      - text: Delete ClickStack role {role} on service {service} in org {org}.
        slots:
          role: path.clickStackRoleId
          service: path.serviceId
          org: path.organizationId
      - text: Remove the unused custom ClickStack team role {role} from service {service} in organization {org}.
        slots:
          role: path.clickStackRoleId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/saved-searches'].get
  update:
    x-apievangelist-phrasing:
      intent: List ClickStack saved searches
      effect: read
      questions:
      - Which saved log and trace searches does my team have in ClickStack?
      - Can I page through saved searches with limit and offset?
      instructions:
      - text: List ClickStack saved searches on service {service} in org {org}.
        slots:
          service: path.serviceId
          org: path.organizationId
      - text: Get {limit} saved searches from offset {offset} for service {service} in organization {org}.
        slots:
          limit: query.limit
          offset: query.offset
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/saved-searches'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a ClickStack search
      effect: write
      questions:
      - How do I save a log search with a where clause so my team can reuse it?
      - Can a saved search specify which columns to select and how to sort?
      instructions:
      - text: Save a search named {name} on source {sourceId} where {where} for service {service} in org {org}.
        slots:
          name: requestBody.name
          sourceId: requestBody.sourceId
          where: requestBody.where
          service: path.serviceId
          org: path.organizationId
      - text: Create saved search {name} over source {sourceId} selecting {select} ordered by {orderBy} for service {service} in organization {org}.
        slots:
          name: requestBody.name
          sourceId: requestBody.sourceId
          select: requestBody.select
          orderBy: requestBody.orderBy
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/saved-searches/{clickStackSavedSearchId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one ClickStack saved search
      effect: read
      questions:
      - What query and filters does a particular saved search use?
      - Which source is a specific saved search built on?
      instructions:
      - text: Get saved search {search} on service {service} in org {org}.
        slots:
          search: path.clickStackSavedSearchId
          service: path.serviceId
          org: path.organizationId
      - text: Show the where clause of saved search {search} for service {service} in organization {org}.
        slots:
          search: path.clickStackSavedSearchId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/saved-searches/{clickStackSavedSearchId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an existing ClickStack saved search
      effect: write
      questions:
      - How do I change the filter on a search I already saved?
      - Does updating a saved search overwrite fields I leave out?
      instructions:
      - text: Update saved search {search} on service {service} in org {org} to name {name}, source {sourceId}, where {where}.
        slots:
          search: path.clickStackSavedSearchId
          service: path.serviceId
          org: path.organizationId
          name: requestBody.name
          sourceId: requestBody.sourceId
          where: requestBody.where
      - text: Replace existing saved search {search} for service {service} in organization {org} with name {name} on source {sourceId}.
        slots:
          search: path.clickStackSavedSearchId
          service: path.serviceId
          org: path.organizationId
          name: requestBody.name
          sourceId: requestBody.sourceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/organizations/{organizationId}/services/{serviceId}/clickstack/saved-searches/{clickStackSavedSearchId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a ClickStack saved search and its alerts
      effect: destructive
      questions:
      - What happens to alerts attached to a saved search when I delete it?
      - How do I remove a saved search from ClickStack?
      instructions:
      - text: Delete saved search {search} on service {service} in org {org}.
        slots:
          search: path.clickStackSavedSearchId
          service: path.serviceId
          org: path.organizationId
      - text: Remove saved search {search} and any alerts on it from service {service} in organization {org}.
        slots:
          search: path.clickStackSavedSearchId
          service: path.serviceId
          org: path.organizationId
      method: generated
      generated: '2026-09-26'