# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Clusters API
  version: 1.0.0
extends: openapi/harness-clusters-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: 17
- target: $.paths['/ng/api/gitops/clusters/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a GitOps cluster linked to an environment
      effect: read
      questions:
      - Which cluster is linked to a given Harness environment under a specific identifier?
      - Can I see an environment-linked cluster link even if it was deleted?
      instructions:
      - text: Get the cluster link {identifier} on environment {environment}.
        slots:
          identifier: path.identifier
          environment: query.environmentIdentifier
      - text: Show environment {environment}'s linked cluster {identifier} in account {account}.
        slots:
          environment: query.environmentIdentifier
          identifier: path.identifier
          account: query.accountIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/gitops/clusters/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a cluster from an environment
      effect: destructive
      questions:
      - How do I detach one GitOps cluster from a Harness environment?
      - Does unlinking a cluster from an environment delete the cluster itself?
      instructions:
      - text: Unlink cluster {identifier} from environment {environment}.
        slots:
          identifier: path.identifier
          environment: query.environmentIdentifier
      - text: Detach cluster {identifier} from environment {environment} in account {account}.
        slots:
          identifier: path.identifier
          environment: query.environmentIdentifier
          account: query.accountIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/gitops/clusters'].get
  update:
    x-apievangelist-phrasing:
      intent: List clusters linked to an environment
      effect: read
      questions:
      - Which GitOps clusters are linked to my staging environment?
      - Can I search the clusters attached to an environment by name?
      instructions:
      - text: List clusters linked to environment {environment}.
        slots:
          environment: query.environmentIdentifier
      - text: Search clusters linked to environment {environment} for {searchTerm}.
        slots:
          environment: query.environmentIdentifier
          searchTerm: query.searchTerm
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/gitops/clusters'].post
  update:
    x-apievangelist-phrasing:
      intent: Link one GitOps cluster to an environment
      effect: write
      questions:
      - How do I attach a single GitOps cluster to a Harness environment?
      - Can I link a cluster managed by a particular GitOps agent to an environment?
      instructions:
      - text: Link cluster {identifier} to environment {envRef}.
        slots:
          identifier: requestBody.identifier
          envRef: requestBody.envRef
      - text: Attach cluster {identifier} from agent {agent} to environment {envRef}.
        slots:
          identifier: requestBody.identifier
          agent: requestBody.agentIdentifier
          envRef: requestBody.envRef
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/gitops/clusters/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Link several clusters to an environment at once
      effect: write
      questions:
      - Can I link many GitOps clusters to one environment in a single call?
      - Is there a way to link every available cluster to an environment at once?
      instructions:
      - text: Link clusters {clusters} to environment {envRef} in one batch.
        slots:
          clusters: requestBody.clusters
          envRef: requestBody.envRef
      - text: Link all available clusters to environment {envRef}.
        slots:
          envRef: requestBody.envRef
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ng/api/gitops/clusters/batchunlink'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink several clusters from an environment
      effect: destructive
      questions:
      - How do I detach many clusters from an environment at once?
      - Can I unlink every cluster from an environment in one request?
      instructions:
      - text: Unlink clusters {clusters} from environment {envRef} in one batch.
        slots:
          clusters: requestBody.clusters
          envRef: requestBody.envRef
      - text: Unlink all clusters from environment {envRef}.
        slots:
          envRef: requestBody.envRef
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/cluster_byname'].get
  update:
    x-apievangelist-phrasing:
      intent: Find an agent's cluster by name
      effect: read
      questions:
      - Can I look up a cluster a GitOps agent manages using its cluster name?
      - What is registered on my GitOps agent under a particular cluster name?
      instructions:
      - text: Find the cluster named {name} on GitOps agent {agent}.
        slots:
          name: query.name
          agent: path.agentIdentifier
      - text: Look up agent {agent}'s cluster by name {name} in project {project}.
        slots:
          agent: path.agentIdentifier
          name: query.name
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/cluster_byurl'].get
  update:
    x-apievangelist-phrasing:
      intent: Find an agent's cluster by server URL
      effect: read
      questions:
      - Which cluster on my GitOps agent points at a given Kubernetes API server URL?
      - Can I resolve a cluster from its server address instead of its identifier?
      instructions:
      - text: Find the cluster with server URL {server} on GitOps agent {agent}.
        slots:
          server: query.server
          agent: path.agentIdentifier
      - text: Look up agent {agent}'s cluster at {server}.
        slots:
          agent: path.agentIdentifier
          server: query.server
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/clusters'].get
  update:
    x-apievangelist-phrasing:
      intent: List clusters managed by a GitOps agent
      effect: read
      questions:
      - Which clusters does a specific GitOps agent manage?
      - Can I narrow an agent's cluster list to one Argo project?
      instructions:
      - text: List clusters managed by GitOps agent {agent}.
        slots:
          agent: path.agentIdentifier
      - text: List agent {agent}'s clusters in Argo project {argoProject}.
        slots:
          agent: path.agentIdentifier
          argoProject: query.query.project
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/clusters'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a cluster on a GitOps agent
      effect: write
      questions:
      - How do I add a new Kubernetes cluster to a Harness GitOps agent?
      - Can I upsert a cluster on an agent if it already exists?
      instructions:
      - text: Create cluster {identifier} on GitOps agent {agent} with config {cluster}.
        slots:
          identifier: query.identifier
          agent: path.agentIdentifier
          cluster: requestBody.cluster
      - text: Add cluster {cluster} on agent {agent}, overwriting it if it exists (upsert {upsert}).
        slots:
          cluster: requestBody.cluster
          agent: path.agentIdentifier
          upsert: requestBody.upsert
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/clusters/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a GitOps agent cluster by identifier
      effect: read
      questions:
      - What is the configuration of a cluster registered on my GitOps agent?
      - Can I fetch a single agent cluster by its Harness identifier?
      instructions:
      - text: Get cluster {identifier} on GitOps agent {agent}.
        slots:
          identifier: path.identifier
          agent: path.agentIdentifier
      - text: Show agent {agent}'s cluster {identifier} in project {project}.
        slots:
          agent: path.agentIdentifier
          identifier: path.identifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/clusters/{identifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a cluster on a GitOps agent
      effect: write
      questions:
      - How do I change the configuration of a cluster registered on a GitOps agent?
      - Can I force an update to an agent cluster or only touch specific fields?
      instructions:
      - text: Update cluster {identifier} on agent {agent} with {cluster}.
        slots:
          identifier: path.identifier
          agent: path.agentIdentifier
          cluster: requestBody.cluster
      - text: Change only fields {updatedFields} on agent {agent}'s cluster {identifier}.
        slots:
          updatedFields: requestBody.updatedFields
          agent: path.agentIdentifier
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/clusters/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a cluster from a GitOps agent
      effect: destructive
      questions:
      - How do I remove a cluster from a GitOps agent entirely?
      - Can I force-delete an agent cluster that is still in use?
      instructions:
      - text: Delete cluster {identifier} from GitOps agent {agent}.
        slots:
          identifier: path.identifier
          agent: path.agentIdentifier
      - text: Delete agent {agent}'s cluster {identifier} with force delete set to {forceDelete}.
        slots:
          agent: path.agentIdentifier
          identifier: path.identifier
          forceDelete: query.forceDelete
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/gpgkeys'].get
  update:
    x-apievangelist-phrasing:
      intent: List GPG keys on a GitOps agent
      effect: read
      questions:
      - Which GPG keys are configured on my GitOps agent for verifying commits?
      - Can I check whether a specific GPG key ID is present on an agent?
      instructions:
      - text: List the GPG keys on GitOps agent {agent}.
        slots:
          agent: path.agentIdentifier
      - text: Check agent {agent} for GPG key {keyID}.
        slots:
          agent: path.agentIdentifier
          keyID: query.query.keyID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/hosted/cluster'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Harness-hosted cluster for an agent
      effect: write
      questions:
      - Can Harness host a cluster for my GitOps agent instead of me bringing one?
      - How do I spin up a Harness-hosted cluster for a GitOps agent?
      instructions:
      - text: Create a Harness-hosted cluster for GitOps agent {agent}.
        slots:
          agent: path.agentIdentifier
      - text: Provision a hosted cluster on agent {agent}.
        slots:
          agent: path.agentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/clusters'].post
  update:
    x-apievangelist-phrasing:
      intent: Search GitOps clusters across agents
      effect: read
      questions:
      - Which GitOps clusters exist across all agents in my project?
      - Can I search clusters and include child org and project scopes?
      instructions:
      - text: Search all GitOps clusters in project {project} for {searchTerm}.
        slots:
          project: requestBody.projectIdentifier
          searchTerm: requestBody.searchTerm
      - text: List GitOps clusters across every agent in account {account}, sorted by {sortBy}.
        slots:
          account: requestBody.accountIdentifier
          sortBy: requestBody.sortBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/clusters/exists'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a GitOps cluster exists
      effect: read
      questions:
      - Is a cluster with this server URL already registered in GitOps?
      - Can I check for an existing cluster before adding it to an agent?
      instructions:
      - text: Check whether a cluster with server {server} exists.
        slots:
          server: query.server
      - text: Check if agent {agent} already has a cluster at {server}.
        slots:
          agent: query.agentIdentifier
          server: query.server
      method: generated
      generated: '2026-09-26'