API Evangelist conversational phrasing for Cohesity Protection Sources API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cohesity Protection Sources API
  version: 1.0.0
extends: openapi/cohesity-protectionsources-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 32
- target: $.paths['/public/physicalAgents/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the backup agent installer for a host
      effect: read
      questions:
      - Where can I get the Cohesity agent installer for a Linux or Windows server?
      - Can I download the agent as an RPM or DEB package for Linux hosts?
      - Is there a separate Go agent and Java agent installer I can pick between?
      instructions:
      - text: Download the physical agent installer for host type {hostType}.
        slots:
          hostType: query.hostType
      - text: Download the {hostType} agent as a {pkgType} package.
        slots:
          hostType: query.hostType
          pkgType: query.pkgType
      - text: Get the {agentType} agent installer for {hostType} hosts.
        slots:
          agentType: query.agentType
          hostType: query.hostType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/physicalAgents/upgrade'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade agents on physical servers
      effect: write
      questions:
      - After upgrading the cluster, how do I bring the agents on my physical servers up to the same release?
      - Can I push an agent upgrade to several physical hosts at once?
      instructions:
      - text: Upgrade the Cohesity agents with ids {agentIds} to the cluster's current agent release.
        slots:
          agentIds: requestBody.agentIds
      - text: Upgrade the agents on my registered physical servers.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse registered sources and their object trees
      effect: read
      questions:
      - How can I see every registered source along with the VMs, folders and databases underneath it?
      - Can I filter the source hierarchy to just VMware or just Office 365 environments?
      - Is there a way to page through a very large source tree a chunk at a time?
      instructions:
      - text: Show the object subtree for protection source {id}.
        slots:
          id: query.id
      - text: Browse the source hierarchy for {environments} environments only.
        slots:
          environments: query.environments
      - text: Show the source tree for {id} including datastores and networks, {numLevels} levels deep.
        slots:
          id: query.id
          numLevels: query.numLevels
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/applicationServers'].get
  update:
    x-apievangelist-phrasing:
      intent: List application servers registered under a source
      effect: read
      questions:
      - Which SQL or Exchange application servers are registered under my vCenter source?
      - Can I list only the hosts running SQL Server within one source tree?
      instructions:
      - text: List application servers under source tree root {protectionSourcesRootNodeId}.
        slots:
          protectionSourcesRootNodeId: query.protectionSourcesRootNodeId
      - text: Show the {application} application servers registered under root {protectionSourcesRootNodeId}.
        slots:
          application: query.application
          protectionSourcesRootNodeId: query.protectionSourcesRootNodeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/applicationServers'].put
  update:
    x-apievangelist-phrasing:
      intent: Change application server registration settings
      effect: write
      questions:
      - How do I change the credentials Cohesity uses for an already registered SQL host?
      - Can I mark an existing application server registration as using a persistent agent?
      instructions:
      - text: Update the application server registration on source {protectionSourceId} to use username {username}.
        slots:
          protectionSourceId: requestBody.protectionSourceId
          username: requestBody.username
      - text: Change the registered applications on source {protectionSourceId} to {applications}.
        slots:
          protectionSourceId: requestBody.protectionSourceId
          applications: requestBody.applications
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/applicationServers'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a host as running SQL or Exchange
      effect: write
      questions:
      - How do I tell Cohesity that a protected host is running Microsoft SQL Server so it can back up the databases?
      - Can I register Exchange as an application on a physical server that is already a source?
      instructions:
      - text: Register source {protectionSourceId} as running {applications} application servers.
        slots:
          protectionSourceId: requestBody.protectionSourceId
          applications: requestBody.applications
      - text: Register SQL on source {protectionSourceId} with username {username} and a persistent agent.
        slots:
          protectionSourceId: requestBody.protectionSourceId
          username: requestBody.username
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/applicationServers/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unregister application servers from a source
      effect: destructive
      questions:
      - Why would unregistering the SQL application on a host fail while a backup is running?
      - Can I remove just the Exchange application from a source but keep the source itself registered?
      instructions:
      - text: Unregister the application servers on protection source {id}.
        slots:
          id: path.id
      - text: Remove the {applications} application registration from source {id}.
        slots:
          applications: requestBody.applications
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/datastores'].get
  update:
    x-apievangelist-phrasing:
      intent: Show datastores used by a VMware VM
      effect: read
      questions:
      - Which VMware datastores does a particular virtual machine live on?
      - Can I look up datastore details for one VM in my vCenter?
      instructions:
      - text: Show datastore information for VMware VM {sourceId}.
        slots:
          sourceId: query.sourceId
      - text: List the datastores backing virtual machine {sourceId}.
        slots:
          sourceId: query.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/diagnostics/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Collect agent diagnostics from a source host
      effect: write
      questions:
      - How can I gather a diagnostics tarball from the agent on a Linux or Windows host for support?
      - Does collecting diagnostics upload the bundle back to the cluster?
      instructions:
      - text: Collect agent diagnostics from protection source {id}.
        slots:
          id: path.id
      - text: Run the diagnostics script on host {id} and upload the tarball to the cluster.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/downloadCftFile'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a CloudFormation template
      effect: read
      questions:
      - Where do I get the CloudFormation template the cluster provides for AWS setup?
      - Can I download a CFT from a specific path on the cluster?
      instructions:
      - text: Download the CloudFormation template named {fileName}.
        slots:
          fileName: requestBody.fileName
      - text: Download CFT file {fileName} from path {filePath}.
        slots:
          fileName: requestBody.fileName
          filePath: requestBody.filePath
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/exchangeDagHosts'].get
  update:
    x-apievangelist-phrasing:
      intent: List hosts in an Exchange DAG
      effect: read
      questions:
      - Which Exchange servers belong to my Database Availability Group?
      - Can I look up DAG members by giving the endpoint of one host in the group?
      instructions:
      - text: List the Exchange hosts in the DAG registered as source {protectionSourceId}.
        slots:
          protectionSourceId: query.protectionSourceId
      - text: Show all members of the Exchange DAG reachable at {endpoint}.
        slots:
          endpoint: query.endpoint
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/objects'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up several source objects by id
      effect: read
      questions:
      - Can I fetch details for a batch of protection source objects in one call?
      - What does the cluster know about a handful of object ids I have from a report?
      instructions:
      - text: Get details for protection source objects {objectIds}.
        slots:
          objectIds: query.objectIds
      - text: List details about the protection source objects I specify.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/objects/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one protection source object
      effect: read
      questions:
      - How do I see the details of a single VM or database object known to the cluster?
      - What attributes does one protection source object carry?
      instructions:
      - text: Get protection source object {id}.
        slots:
          id: path.id
      - text: Show me the details of source object {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/protectedObjects'].get
  update:
    x-apievangelist-phrasing:
      intent: List protected objects in a registered source
      effect: read
      questions:
      - Which VMs in my vCenter are actually protected by a backup job right now?
      - Can I include objects covered by RPO policies when listing what's protected in a source?
      instructions:
      - text: List protected objects in {environment} source {id}.
        slots:
          environment: query.environment
          id: query.id
      - text: Show what is protected in source {id} of type {environment}, including RPO-protected objects.
        slots:
          id: query.id
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/refresh/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh a source's inventory
      effect: write
      questions:
      - I just added a VM in vCenter; how do I make the cluster see it immediately?
      - Can I force a re-sync of the object hierarchy for one registered source?
      instructions:
      - text: Refresh the inventory of protection source {id}.
        slots:
          id: path.id
      - text: Force an immediate re-sync of the source tree rooted at {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/register'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a source via the v1 public endpoint
      effect: write
      questions:
      - How do I register a vCenter or physical server with the older public v1 register endpoint?
      - Can I set a throttling policy and source-side dedup when registering a source the v1 way?
      - Which credentials can the v1 register call accept, such as AWS, Azure, GCP or Kubernetes?
      instructions:
      - text: Register a {environment} source at {endpoint} through the v1 public register endpoint.
        slots:
          environment: requestBody.environment
          endpoint: requestBody.endpoint
      - text: Register physical host {endpoint} with the v1 endpoint, forcing registration even if another cluster owns its agent.
        slots:
          endpoint: requestBody.endpoint
      - text: Use the v1 register endpoint to add vCenter {endpoint} with username {username}.
        slots:
          endpoint: requestBody.endpoint
          username: requestBody.username
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/registrationInfo'].get
  update:
    x-apievangelist-phrasing:
      intent: Show registration and protection info for sources
      effect: read
      questions:
      - How much of each registered source is protected, and when was it registered?
      - Can I get registration info including the applications tree for my SQL hosts?
      instructions:
      - text: Show registration and protection info for registered sources {ids}.
        slots:
          ids: query.ids
      - text: Get registration info for {environments} sources, including the applications tree.
        slots:
          environments: query.environments
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/rootNodes'].get
  update:
    x-apievangelist-phrasing:
      intent: List top-level registered sources
      effect: read
      questions:
      - What top-level sources like vCenters and NAS arrays are registered on the cluster?
      - Can I list only the root sources of one environment type?
      instructions:
      - text: List the root protection sources for {environments}.
        slots:
          environments: query.environments
      - text: Show registration information for root source {id}.
        slots:
          id: query.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/sqlAagHostsAndDatabases'].get
  update:
    x-apievangelist-phrasing:
      intent: List SQL Always On groups and databases
      effect: read
      questions:
      - Which Always On Availability Groups and databases are found on my registered SQL servers?
      - Can I see AAG membership for several SQL sources at once?
      instructions:
      - text: List the AAGs and their databases for SQL sources {sqlProtectionSourceIds}.
        slots:
          sqlProtectionSourceIds: query.sqlProtectionSourceIds
      - text: Show Always On databases on SQL servers {sqlProtectionSourceIds}.
        slots:
          sqlProtectionSourceIds: query.sqlProtectionSourceIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/virtualMachines'].get
  update:
    x-apievangelist-phrasing:
      intent: List VMs across registered vCenters
      effect: read
      questions:
      - Which virtual machines in my vCenter are not yet protected by any job?
      - Can I find a VM by its exact name or UUID across all registered vCenter servers?
      instructions:
      - text: List the VMs in vCenter {vCenterId}.
        slots:
          vCenterId: query.vCenterId
      - text: Find the virtual machine named {names}.
        slots:
          names: query.names
      - text: List unprotected VMs in vCenter {vCenterId}.
        slots:
          vCenterId: query.vCenterId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unregister a source via the v1 endpoint
      effect: destructive
      questions:
      - What happens if I unregister a vCenter source from the cluster with the v1 public endpoint?
      - Can I remove a physical server I no longer back up from the v1 source list?
      instructions:
      - text: Unregister protection source {id} using the v1 public endpoint.
        slots:
          id: path.id
      - text: Remove source {id} from the cluster's v1 registered sources.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/public/protectionSources/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a registered source's settings
      effect: write
      questions:
      - How do I change the password stored for a registered source?
      - Can I set a minimum free space threshold that cancels backups when a source runs low?
      - Is it possible to switch an Exchange Online source to OAuth after it's registered?
      instructions:
      - text: Update source {id} to use username {username} and a new password.
        slots:
          id: path.id
          username: requestBody.username
      - text: Set the minimum free space on source {id} to {minimumFreeSpaceGB} GB.
        slots:
          id: path.id
          minimumFreeSpaceGB: requestBody.minimumFreeSpaceGB
      - text: Change the endpoint of registered source {id} to {endpoint}.
        slots:
          id: path.id
          endpoint: requestBody.endpoint
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources'].get
  update:
    x-apievangelist-phrasing:
      intent: List protection sources (v2)
      effect: read
      questions:
      - What protection sources do I have under the v2 data-protect API?
      - Can I include sources owned by all tenants when listing sources?
      - Is there a way to get the sources' credentials back encrypted with my own key?
      instructions:
      - text: List protection sources for tenants {tenantIds}.
        slots:
          tenantIds: query.tenantIds
      - text: List all sources with credentials encrypted using key {encryptionKey}.
        slots:
          encryptionKey: query.encryptionKey
      - text: Show every protection source across all tenants.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/filters'].get
  update:
    x-apievangelist-phrasing:
      intent: List attribute filters for a source
      effect: read
      questions:
      - What attributes can I filter leaf objects on within a given source?
      - Can I see the available attribute filters for VMs under one parent source?
      instructions:
      - text: List attribute filters for source {sourceUuid}.
        slots:
          sourceUuid: query.sourceUuid
      - text: Show the {environment} attribute filters available under source {sourceUuid}.
        slots:
          environment: query.environment
          sourceUuid: query.sourceUuid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/registrations'].get
  update:
    x-apievangelist-phrasing:
      intent: List source registrations
      effect: read
      questions:
      - Which source registrations exist on the cluster in the v2 API?
      - Can I filter source registrations to a specific set of registration ids?
      instructions:
      - text: List source registrations {ids}.
        slots:
          ids: query.ids
      - text: Show source registrations for tenants {tenantIds}.
        slots:
          tenantIds: query.tenantIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/registrations'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a source via the v2 registrations API
      effect: write
      questions:
      - How do I register a new source using the v2 data-protect registrations endpoint?
      - Can a v2 source registration go through a specific connection when the source is behind a connector?
      instructions:
      - text: Register a new {environment} source through the v2 registrations API.
        slots:
          environment: requestBody.environment
      - text: Register a {environment} source reachable through connection {connectionId}.
        slots:
          environment: requestBody.environment
          connectionId: requestBody.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/registrations/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a source registration
      effect: read
      questions:
      - How do I look up one source registration and its settings?
      - What details are stored on a specific v2 source registration?
      instructions:
      - text: Get source registration {id}.
        slots:
          id: path.id
      - text: Show me the details of registration {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/registrations/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a source registration
      effect: write
      questions:
      - Can I change which connection a v2 source registration uses?
      - How would I re-encrypt the stored credentials on an existing registration?
      instructions:
      - text: Update source registration {id} for environment {environment}.
        slots:
          id: path.id
          environment: requestBody.environment
      - text: Point registration {id} at connection {connectionId}.
        slots:
          id: path.id
          connectionId: requestBody.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/registrations/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a source registration
      effect: destructive
      questions:
      - How do I delete a v2 source registration I no longer need?
      - Is deleting a source registration permanent?
      instructions:
      - text: Delete source registration {id}.
        slots:
          id: path.id
      - text: Remove the v2 registration {id} from the cluster.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/test-connection'].post
  update:
    x-apievangelist-phrasing:
      intent: Test connectivity to a source before registering
      effect: read
      questions:
      - Can I check that the cluster can reach my SQL or Cassandra source before registering it?
      - How would I verify HDFS or Hive connection parameters work?
      instructions:
      - text: Test the connection to a {environment} source.
        slots:
          environment: requestBody.environment
      - text: Test connectivity to a {environment} source using parameters {mssqlConnectionParams}.
        slots:
          environment: requestBody.environment
          mssqlConnectionParams: requestBody.mssqlConnectionParams
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/virtual-datacenter/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get VMware virtual datacenter details
      effect: read
      questions:
      - What catalogs and org networks are associated with a VMware virtual datacenter?
      - Can I inspect a VDC's details before restoring into it?
      instructions:
      - text: Get details for virtual datacenter {id}.
        slots:
          id: path.id
      - text: Show the catalogs and org networks of VDC {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/sources/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a protection source (v2)
      effect: read
      questions:
      - How do I fetch one protection source by id in the v2 API?
      - What does the v2 API return for a single source?
      instructions:
      - text: Get protection source {id} from the v2 sources API.
        slots:
          id: path.id
      - text: Show source {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'