# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity.DirectoryManagement Directory.recovery API
  version: 1.0.0
extends: openapi/azure-ad-directory-recovery-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: 22
- target: $.paths['/directory/recovery'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the directory recovery settings
      effect: read
      questions:
      - What does the directory recovery resource in Microsoft Entra contain?
      - Can I see the recovery setup for my directory, including its jobs and snapshots?
      instructions:
      - text: Show the directory recovery resource.
      - text: Get the recovery configuration for my directory.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete the directory recovery resource
      effect: destructive
      questions:
      - Is it possible to delete the whole recovery resource from the directory?
      - What happens if I remove the directory recovery navigation property?
      instructions:
      - text: Delete the directory recovery resource.
      - text: Remove the recovery object from the directory entirely.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update the directory recovery resource
      effect: write
      questions:
      - How do I change the directory recovery resource as a whole?
      - Can I patch the recovery object that holds my jobs and snapshots?
      instructions:
      - text: Update the directory recovery resource.
      - text: Replace the list of recovery jobs on the directory recovery object with {jobs}.
        slots:
          jobs: requestBody.jobs
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List directory recovery jobs
      effect: read
      questions:
      - Which recovery jobs have been run against my directory?
      - Can I see the status of all directory restore jobs?
      instructions:
      - text: List all directory recovery jobs.
      - text: Show every recovery job with its status and start time.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a directory recovery job
      effect: write
      questions:
      - How do I start a job to restore directory objects to an earlier state?
      - Can I limit a recovery job with filtering criteria?
      instructions:
      - text: Create a recovery job that restores the directory to its state at {target_time}.
        slots:
          target_time: requestBody.targetStateDateTime
      - text: Start a recovery job targeting {target_time} using filtering criteria {criteria}.
        slots:
          target_time: requestBody.targetStateDateTime
          criteria: requestBody.filteringCriteria
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/jobs/{recoveryJobBase-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a directory recovery job
      effect: read
      questions:
      - What's the status of a specific directory recovery job?
      - How many objects did a given recovery job calculate as changed?
      instructions:
      - text: Get recovery job {job_id}.
        slots:
          job_id: path.recoveryJobBase-id
      - text: Show the status and completion time of recovery job {job_id}.
        slots:
          job_id: path.recoveryJobBase-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/jobs/{recoveryJobBase-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a directory recovery job
      effect: destructive
      questions:
      - How do I delete an old directory recovery job record?
      - Can a recovery job entry be removed after it finishes?
      instructions:
      - text: Delete recovery job {job_id}.
        slots:
          job_id: path.recoveryJobBase-id
      - text: Remove the recovery job record {job_id} from the directory.
        slots:
          job_id: path.recoveryJobBase-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/jobs/{recoveryJobBase-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a directory recovery job
      effect: write
      questions:
      - Can I change the target restore time on an existing recovery job?
      - How do I edit the filtering criteria of a recovery job I already created?
      instructions:
      - text: Change the target state time of recovery job {job_id} to {target_time}.
        slots:
          job_id: path.recoveryJobBase-id
          target_time: requestBody.targetStateDateTime
      - text: Update the filtering criteria on recovery job {job_id} to {criteria}.
        slots:
          job_id: path.recoveryJobBase-id
          criteria: requestBody.filteringCriteria
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/jobs/{recoveryJobBase-id}/microsoft.graph.entraRecoveryServices.cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running directory recovery job
      effect: destructive
      questions:
      - How do I stop a directory recovery job that's still running?
      - Can I abort a restore job partway through?
      instructions:
      - text: Cancel recovery job {job_id}.
        slots:
          job_id: path.recoveryJobBase-id
      - text: Abort the in-progress directory restore job {job_id}.
        slots:
          job_id: path.recoveryJobBase-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/jobs/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count directory recovery jobs
      effect: read
      questions:
      - How many recovery jobs exist for my directory?
      - What's the total number of restore jobs we've run?
      instructions:
      - text: Count the directory recovery jobs.
      - text: Tell me how many recovery jobs there are.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots'].get
  update:
    x-apievangelist-phrasing:
      intent: List directory recovery snapshots
      effect: read
      questions:
      - Which backup snapshots of my directory are available to restore from?
      - Can I see when each directory snapshot was taken?
      instructions:
      - text: List all directory recovery snapshots.
      - text: Show every snapshot with its creation time and number of changed objects.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a directory recovery snapshot
      effect: write
      questions:
      - How do I add a new snapshot record to directory recovery?
      - Can I create a snapshot entry through the API?
      instructions:
      - text: Create a new directory recovery snapshot.
      - text: Add a recovery snapshot dated {created_time}.
        slots:
          created_time: requestBody.createdDateTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a directory recovery snapshot
      effect: read
      questions:
      - What does a particular directory snapshot contain?
      - How many objects changed in a given recovery snapshot?
      instructions:
      - text: Get recovery snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      - text: Show the creation time and changed object count of snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a directory recovery snapshot
      effect: destructive
      questions:
      - How do I delete a directory snapshot we no longer need?
      - Can I remove a recovery snapshot permanently?
      instructions:
      - text: Delete recovery snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      - text: Remove directory snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a directory recovery snapshot
      effect: write
      questions:
      - Can I edit the properties of an existing directory snapshot?
      - How do I change the recorded changed-object total on a snapshot?
      instructions:
      - text: Update recovery snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      - text: Set the total changed objects on snapshot {snapshot_id} to {total}.
        slots:
          snapshot_id: path.snapshot-id
          total: requestBody.totalChangedObjects
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}/recoveryJobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List recovery jobs run from a snapshot
      effect: read
      questions:
      - Which restore jobs were run from a particular snapshot?
      - Has anyone actually restored from this directory snapshot?
      instructions:
      - text: List the recovery jobs for snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      - text: Show every restore job that used snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}/recoveryJobs/{recoveryJob-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a recovery job belonging to a snapshot
      effect: read
      questions:
      - What's the status of one restore job run from a given snapshot?
      - Can I look up a snapshot's recovery job by its id?
      instructions:
      - text: Get recovery job {job_id} of snapshot {snapshot_id}.
        slots:
          job_id: path.recoveryJob-id
          snapshot_id: path.snapshot-id
      - text: Show the progress of restore job {job_id} started from snapshot {snapshot_id}.
        slots:
          job_id: path.recoveryJob-id
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}/recoveryJobs/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count recovery jobs run from a snapshot
      effect: read
      questions:
      - How many restore jobs have used a particular snapshot?
      - What's the number of recovery jobs tied to this snapshot?
      instructions:
      - text: Count the recovery jobs for snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      - text: Tell me how many restore jobs ran from snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List recovery preview jobs for a snapshot
      effect: read
      questions:
      - Which preview jobs have been run to see what restoring a snapshot would change?
      - Can I list the dry-run previews for a directory snapshot?
      instructions:
      - text: List the dry-run preview jobs for snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      - text: Show every restore preview run against snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs/{recoveryPreviewJob-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a recovery preview job for a snapshot
      effect: read
      questions:
      - What did a specific restore preview report for a snapshot?
      - Can I check the results of one recovery preview job by id?
      instructions:
      - text: Get recovery preview job {preview_id} of snapshot {snapshot_id}.
        slots:
          preview_id: path.recoveryPreviewJob-id
          snapshot_id: path.snapshot-id
      - text: Show the preview results of job {preview_id} for snapshot {snapshot_id}.
        slots:
          preview_id: path.recoveryPreviewJob-id
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count recovery preview jobs for a snapshot
      effect: read
      questions:
      - How many restore previews have been run on a snapshot?
      - What's the count of preview jobs attached to this snapshot?
      instructions:
      - text: Count the dry-run previews run on snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      - text: Tell me how many restore previews ran on snapshot {snapshot_id}.
        slots:
          snapshot_id: path.snapshot-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/directory/recovery/snapshots/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count directory recovery snapshots
      effect: read
      questions:
      - How many directory snapshots are available?
      - What's the total number of recovery snapshots we have?
      instructions:
      - text: Count the directory recovery snapshots.
      - text: Tell me how many snapshots exist for directory recovery.
      method: generated
      generated: '2026-10-01'