# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Agents API
  version: 1.0.0
extends: openapi/harness-agents-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: 25
- target: $.paths['/gitops/api/v1/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List GitOps agents
      effect: read
      questions:
      - Which GitOps agents are registered in my Harness project?
      - Can I list only the GitOps agents that are disconnected or unhealthy?
      - How do I page through all my GitOps agents sorted by name?
      instructions:
      - text: List the GitOps agents in project {project}.
        slots:
          project: query.projectIdentifier
      - text: Show GitOps agents whose health status is {health}.
        slots:
          health: query.healthStatus
      - text: List all my GitOps agents.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new GitOps agent
      effect: write
      questions:
      - How do I register a new GitOps agent in Harness?
      - Can I create a GitOps agent scoped to a single project rather than the whole account?
      instructions:
      - text: Create a GitOps agent named {name} with identifier {identifier}.
        slots:
          name: requestBody.name
          identifier: requestBody.identifier
      - text: Register a new GitOps agent {name} in project {project} of org {org}.
        slots:
          name: requestBody.name
          project: requestBody.projectIdentifier
          org: requestBody.orgIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/ns'].get
  update:
    x-apievangelist-phrasing:
      intent: List namespaces GitOps agents run in
      effect: read
      questions:
      - Which Kubernetes namespaces are my GitOps agents installed in?
      - What namespaces are in use by agents in this project?
      instructions:
      - text: List the namespaces used by GitOps agents in project {project}.
        slots:
          project: query.projectIdentifier
      - text: Show every namespace my GitOps agents are deployed into.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search GitOps agents with filters
      effect: read
      questions:
      - Can I search GitOps agents by a search term and filter by mapped projects?
      - Is there a way to run a filtered search over agents with a request body instead of query params?
      instructions:
      - text: Search GitOps agents matching {term}.
        slots:
          term: requestBody.searchTerm
      - text: Search for GitOps agents of type {type} that are {connected}.
        slots:
          type: requestBody.type
          connected: requestBody.connectedStatus
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List tags used on GitOps agents
      effect: read
      questions:
      - What tags have been applied to my GitOps agents?
      - Which agent tags exist in this org so I can filter by them?
      instructions:
      - text: List the tags on GitOps agents in org {org}.
        slots:
          org: query.orgIdentifier
      - text: Show all distinct GitOps agent tags.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions of GitOps agents
      effect: read
      questions:
      - Which versions are my GitOps agents running?
      - Are my agents on different versions across this project?
      instructions:
      - text: List the versions of GitOps agents in project {project}.
        slots:
          project: query.projectIdentifier
      - text: Show which GitOps agent versions are in use.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agent.identifier}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a GitOps agent's details
      effect: write
      questions:
      - Can I change the tags or metadata on an existing GitOps agent?
      - How do I rename or update the description of a GitOps agent?
      instructions:
      - text: Update GitOps agent {agent} to have the description {description}.
        slots:
          agent: path.agent.identifier
          description: requestBody.description
      - text: Change the tags on GitOps agent {agent} to {tags}.
        slots:
          agent: path.agent.identifier
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/deploy.yaml'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an agent's install manifest YAML
      effect: read
      questions:
      - Where do I get the Kubernetes YAML manifest to install a GitOps agent?
      - Can I fetch the agent install YAML for a specific namespace and skip the CRDs?
      instructions:
      - text: Get the deployment YAML for GitOps agent {agent} in namespace {namespace}.
        slots:
          agent: path.agentIdentifier
          namespace: query.namespace
      - text: Download the install manifest for agent {agent} without CRDs.
        slots:
          agent: path.agentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/deployment-spec/helm'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate an agent Helm chart from settings
      effect: read
      questions:
      - Can I generate the GitOps agent Helm chart by posting proxy and Argo CD settings in the body?
      - What do I send to build a Helm chart for an agent with a custom CA and proxy?
      instructions:
      - text: Generate the Helm chart for agent {agent} using proxy settings {proxy}.
        slots:
          agent: path.agentIdentifier
          proxy: requestBody.proxy
      - text: Build a Helm chart for GitOps agent {agent} targeting namespace {namespace} via a POST request.
        slots:
          agent: path.agentIdentifier
          namespace: requestBody.namespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/deployment-spec/yaml'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate agent install YAML from posted settings
      effect: read
      questions:
      - Can I post my proxy and private key settings to get a GitOps agent install YAML back?
      - Is there a POST version of the agent manifest generator that takes Argo CD settings?
      instructions:
      - text: Generate install YAML for agent {agent} with Argo CD settings {argocd} in the request body.
        slots:
          agent: path.agentIdentifier
          argocd: requestBody.argocdSettings
      - text: Post deployment settings for agent {agent} and return the plain YAML manifest for namespace {namespace}.
        slots:
          agent: path.agentIdentifier
          namespace: requestBody.namespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/helm-chart'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the Helm chart for an agent
      effect: read
      questions:
      - How do I download the Helm chart to install a GitOps agent?
      - Can I get the agent's Helm chart for a disaster recovery node?
      instructions:
      - text: Download the Helm chart for GitOps agent {agent}.
        slots:
          agent: path.agentIdentifier
      - text: Get the Helm chart for agent {agent} for disaster recovery node {dr}.
        slots:
          agent: path.agentIdentifier
          dr: query.disasterRecoveryIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/helm-overrides'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Helm values overrides for an agent
      effect: read
      questions:
      - Where can I get the Helm values overrides file for my GitOps agent?
      - What overrides should I pass to helm install for this agent?
      instructions:
      - text: Get the Helm overrides for GitOps agent {agent}.
        slots:
          agent: path.agentIdentifier
      - text: Fetch the values overrides for agent {agent} in namespace {namespace}.
        slots:
          agent: path.agentIdentifier
          namespace: query.namespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/helm-overrides'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate Helm overrides from posted settings
      effect: read
      questions:
      - Can I post proxy and CA settings to generate Helm overrides for an agent install?
      - Is there a way to build agent Helm values overrides from a request body?
      instructions:
      - text: Generate Helm overrides for agent {agent} posting the CA data {ca}.
        slots:
          agent: path.agentIdentifier
          ca: requestBody.caData
      - text: Build the Helm values overrides for GitOps agent {agent} with a POST body.
        slots:
          agent: path.agentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/operator/yaml'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the operator YAML for an agent
      effect: read
      questions:
      - How do I get the operator YAML to deploy a GitOps agent with an operator?
      - Can I download the agent's operator manifest for a given namespace?
      instructions:
      - text: Get the operator YAML for GitOps agent {agent}.
        slots:
          agent: path.agentIdentifier
      - text: Download the operator manifest for agent {agent} in namespace {namespace}.
        slots:
          agent: path.agentIdentifier
          namespace: query.namespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/operator/yaml'].post
  update:
    x-apievangelist-phrasing:
      intent: Generate operator YAML from posted settings
      effect: read
      questions:
      - Can I post my settings to generate an operator-based install YAML for an agent?
      - Is there a POST form of the operator manifest generator that accepts a private key?
      instructions:
      - text: Generate the operator YAML for agent {agent} by posting private key {key}.
        slots:
          agent: path.agentIdentifier
          key: requestBody.privateKey
      - text: Post operator settings for GitOps agent {agent} and return its operator manifest.
        slots:
          agent: path.agentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/primaryNode'].patch
  update:
    x-apievangelist-phrasing:
      intent: Set an agent's primary disaster recovery node
      effect: write
      questions:
      - How do I fail over a GitOps agent to its disaster recovery node?
      - Can I disable sync windows when switching the primary DR node?
      instructions:
      - text: Make disaster recovery node {dr} the primary node for agent {agent}.
        slots:
          dr: requestBody.disasterRecoveryIdentifier
          agent: path.agentIdentifier
      - text: Switch agent {agent} to its DR node and disable sync windows.
        slots:
          agent: path.agentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/sync-allowed'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether an agent is allowed to sync
      effect: read
      questions:
      - Is syncing currently allowed for this GitOps agent?
      - Can I check if deny sync windows are blocking an agent?
      instructions:
      - text: Check whether GitOps agent {agent} is allowed to sync.
        slots:
          agent: path.agentIdentifier
      - text: Show the sync-allowed status of agent {agent}.
        slots:
          agent: path.agentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{agentIdentifier}/sync-allowed'].put
  update:
    x-apievangelist-phrasing:
      intent: Allow or block syncs for an agent
      effect: write
      questions:
      - How do I pause all syncs for a GitOps agent?
      - Can I block application syncs by adding deny sync windows to an agent's app projects?
      instructions:
      - text: Set sync allowed to {allowed} for GitOps agent {agent}.
        slots:
          allowed: requestBody.syncAllowed
          agent: path.agentIdentifier
      - text: Block syncs on agent {agent} by creating deny sync windows.
        slots:
          agent: path.agentIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{identifier}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a GitOps agent's details
      effect: read
      questions:
      - What are the details and health of a specific GitOps agent?
      - Can I look up one agent by its identifier and include its credentials?
      instructions:
      - text: Get GitOps agent {identifier}.
        slots:
          identifier: path.identifier
      - text: Show details for agent {identifier} in project {project}.
        slots:
          identifier: path.identifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{identifier}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a GitOps agent
      effect: destructive
      questions:
      - How do I remove a GitOps agent I no longer use?
      - Can I delete an agent that belongs to a specific project?
      instructions:
      - text: Delete GitOps agent {identifier}.
        slots:
          identifier: path.identifier
      - text: Remove agent {identifier} from project {project}.
        slots:
          identifier: path.identifier
          project: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{identifier}/credentials'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate a GitOps agent's credentials
      effect: write
      questions:
      - How do I rotate the credentials a GitOps agent uses to connect?
      - Can I issue fresh credentials for an agent whose secret leaked?
      instructions:
      - text: Regenerate credentials for GitOps agent {identifier}.
        slots:
          identifier: path.identifier
      - text: Issue new connection credentials for agent {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{identifier}/scale'].post
  update:
    x-apievangelist-phrasing:
      intent: Scale a hosted GitOps agent
      effect: write
      questions:
      - How do I change the number of replicas for a Harness-hosted GitOps agent?
      - Can I scale up a hosted agent to handle more applications?
      instructions:
      - text: Scale hosted agent {identifier} to {replicas} replicas.
        slots:
          identifier: path.identifier
          replicas: requestBody.replicas
      - text: Scale up hosted GitOps agent {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{identifier}/secret-resolution/enabled'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if secret resolution is enabled for an agent
      effect: read
      questions:
      - Is Harness secret resolution turned on for this GitOps agent?
      - Can an agent resolve Harness secrets in its manifests?
      instructions:
      - text: Check whether secret resolution is enabled on agent {identifier}.
        slots:
          identifier: path.identifier
      - text: Tell me if GitOps agent {identifier} can resolve Harness secrets.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v1/agents/{identifier}/unique'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an agent identifier for uniqueness
      effect: read
      questions:
      - Is this GitOps agent identifier already taken?
      - Can I verify an agent identifier is unique before creating it?
      instructions:
      - text: Check if agent identifier {identifier} is unique.
        slots:
          identifier: path.identifier
      - text: Verify no other GitOps agent already uses {identifier}.
        slots:
          identifier: path.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gitops/api/v2/versions/agents/upgrade-available'].get
  update:
    x-apievangelist-phrasing:
      intent: Check for a newer GitOps agent version
      effect: read
      questions:
      - Is there a newer GitOps agent version I should upgrade to?
      - What agent upgrade is available for the version I'm running?
      instructions:
      - text: Check whether an upgrade is available for agent version {version}.
        slots:
          version: query.existingVersion
      - text: See if a new GitOps agent release is out.
      method: generated
      generated: '2026-09-26'