# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cohesity REST Protection Groups API
  version: 1.0.0
extends: openapi/cohesity-protection-groups-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: 16
- target: $.paths['/data-protect/protection-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List protection groups
      effect: read
      questions:
      - Which protection groups had their last backup fail?
      - Can I list only paused protection groups, or only those with a DataLock?
      - Which backup groups missed their SLA on the last run?
      instructions:
      - text: List protection groups named {names}.
        slots:
          names: query.names
      - text: Show protection groups using policy {policyIds} with last run info.
        slots:
          policyIds: query.policyIds
      - text: List {environments} protection groups whose last local backup was {lastRunLocalBackupStatus}.
        slots:
          environments: query.environments
          lastRunLocalBackupStatus: query.lastRunLocalBackupStatus
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a protection group
      effect: write
      questions:
      - How do I set up a new backup group for my VMware VMs with a given policy?
      - Can I create a protection group that starts paused?
      - Is it possible to set an SLA and alert policy when creating a group?
      instructions:
      - text: Create protection group {name} for {environment} using policy {policyId}.
        slots:
          name: requestBody.name
          environment: requestBody.environment
          policyId: requestBody.policyId
      - text: Create a paused {environment} protection group {name} on policy {policyId} writing to storage domain {storageDomainId}.
        slots:
          environment: requestBody.environment
          name: requestBody.name
          policyId: requestBody.policyId
          storageDomainId: requestBody.storageDomainId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/states'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause, resume or deactivate protection groups in bulk
      effect: write
      questions:
      - Can I pause several backup groups at once during a maintenance window?
      - When does resuming a protection group take effect?
      instructions:
      - text: Apply action {action} to protection groups {ids}.
        slots:
          action: requestBody.action
          ids: requestBody.ids
      - text: Pause protection groups {ids}.
        slots:
          ids: requestBody.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a protection group
      effect: read
      questions:
      - How do I look at a single protection group's configuration and last run?
      - What policy and storage domain is a given backup group using?
      instructions:
      - text: Get protection group {id}.
        slots:
          id: path.id
      - text: Show protection group {id} with its last run info.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a protection group's settings
      effect: write
      questions:
      - Can I switch an existing protection group to a different policy?
      - How do I change the start time or priority of a backup group?
      instructions:
      - text: Update protection group {id} to use policy {policyId}.
        slots:
          id: path.id
          policyId: requestBody.policyId
      - text: Rename protection group {id} to {name}, keeping environment {environment} and policy {policyId}.
        slots:
          id: path.id
          name: requestBody.name
          environment: requestBody.environment
          policyId: requestBody.policyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a protection group
      effect: destructive
      questions:
      - If I delete a backup group, are its snapshots kept?
      - How do I remove a protection group and its snapshots too?
      instructions:
      - text: Delete protection group {id}.
        slots:
          id: path.id
      - text: Delete protection group {id} and its snapshots.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List runs of a protection group
      effect: read
      questions:
      - What were the last backup runs for one protection group and did they succeed?
      - Can I exclude runs that can't be restored from a group's run history?
      - How many runs come back by default for a group?
      instructions:
      - text: List runs for protection group {id}.
        slots:
          id: path.id
      - text: Show the last {numRuns} runs of protection group {id}.
        slots:
          numRuns: query.numRuns
          id: path.id
      - text: List runs of group {id} where local backup status was {localBackupRunStatus}.
        slots:
          id: path.id
          localBackupRunStatus: query.localBackupRunStatus
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs'].put
  update:
    x-apievangelist-phrasing:
      intent: Change retention or resync runs of a group
      effect: write
      questions:
      - Can I extend how long snapshots from a past backup run are kept?
      - How do I retry failed replication copies for an earlier run?
      instructions:
      - text: Update runs of protection group {id} with {updateProtectionGroupRunParams}.
        slots:
          id: path.id
          updateProtectionGroupRunParams: requestBody.updateProtectionGroupRunParams
      - text: Extend retention on runs of group {id} using {updateProtectionGroupRunParams}.
        slots:
          id: path.id
          updateProtectionGroupRunParams: requestBody.updateProtectionGroupRunParams
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an on-demand backup run
      effect: write
      questions:
      - How do I kick off a backup right now instead of waiting for the schedule?
      - Can I run a full backup on demand for just a few objects in a group?
      instructions:
      - text: Run protection group {id} now as a {runType} backup.
        slots:
          id: path.id
          runType: requestBody.runType
      - text: Start a {runType} run of group {id} for objects {objects}.
        slots:
          runType: requestBody.runType
          id: path.id
          objects: requestBody.objects
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs/{runId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single protection group run
      effect: read
      questions:
      - How do I check the result of one specific backup run?
      - Can I see object-level details for a particular run?
      instructions:
      - text: Get run {runId} of protection group {id}.
        slots:
          runId: path.runId
          id: path.id
      - text: Show object details for run {runId} in group {id}.
        slots:
          runId: path.runId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs/{runId}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running backup
      effect: destructive
      questions:
      - Can I stop a backup run that's taking too long?
      - Is it possible to cancel only the replication part of a run?
      instructions:
      - text: Cancel run {runId} of protection group {id}.
        slots:
          runId: path.runId
          id: path.id
      - text: Cancel the replication task {replicationTaskId} in run {runId} of group {id}.
        slots:
          replicationTaskId: requestBody.replicationTaskId
          runId: path.runId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs/{runId}/debug-logs'].get
  update:
    x-apievangelist-phrasing:
      intent: Download debug logs for a backup run
      effect: read
      questions:
      - Where can I get the debug logs for all objects in a failed run?
      - Can I narrow a run's debug logs to one object?
      instructions:
      - text: Get debug logs for run {runId} of group {id}.
        slots:
          runId: path.runId
          id: path.id
      - text: Get run {runId} debug logs from group {id} filtered to object {objectId}.
        slots:
          runId: path.runId
          id: path.id
          objectId: query.objectId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs/{runId}/objects/{objectId}/debug-logs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get debug logs for one object in a run
      effect: read
      questions:
      - How do I pull debug logs for just one VM that failed in a backup run?
      - Is there an object-specific debug log endpoint for a run?
      instructions:
      - text: Get debug logs for object {objectId} in run {runId} of group {id}.
        slots:
          objectId: path.objectId
          runId: path.runId
          id: path.id
      - text: Download the per-object debug log for {objectId}, run {runId}, group {id}.
        slots:
          objectId: path.objectId
          runId: path.runId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/protection-groups/{id}/runs/{runId}/objects/{objectId}/downloadMessages'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a CSV of run errors for an object
      effect: read
      questions:
      - Can I get a CSV listing file paths that errored during a backup of one object?
      - What warnings did a run hit for a specific object, file by file?
      instructions:
      - text: Download the error and warning CSV for object {objectId} in run {runId} of group {id}.
        slots:
          objectId: path.objectId
          runId: path.runId
          id: path.id
      - text: Get the file-level error report for object {objectId}, run {runId}, group {id}.
        slots:
          objectId: path.objectId
          runId: path.runId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/runs/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize runs across all groups
      effect: read
      questions:
      - Which backup runs failed across all protection groups yesterday?
      - Can I get a cluster-wide summary of runs in a time window?
      instructions:
      - text: List protection runs with status {runStatus}.
        slots:
          runStatus: query.runStatus
      - text: Summarize all runs between {startTimeUsecs} and {endTimeUsecs}.
        slots:
          startTimeUsecs: query.startTimeUsecs
          endTimeUsecs: query.endTimeUsecs
      method: generated
      generated: '2026-10-01'
- target: $.paths['/data-protect/runs/{runId}/progress'].get
  update:
    x-apievangelist-phrasing:
      intent: Track progress of a run
      effect: read
      questions:
      - How far along is a backup run that's currently in progress?
      - Can I include finished tasks and event logs in a run's progress?
      instructions:
      - text: Show the progress of run {runId}.
        slots:
          runId: path.runId
      - text: Get progress for run {runId} including finished tasks and event logs.
        slots:
          runId: path.runId
      method: generated
      generated: '2026-10-01'