# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Purview Records Management Retention Labels API
  version: 1.0.0
extends: openapi/microsoft-purview-retention-labels-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: 5
- target: $.paths['/security/labels/retentionLabels'].get
  update:
    x-apievangelist-phrasing:
      intent: List retention labels
      effect: read
      questions:
      - What retention labels are configured in our organization?
      - Can I filter or sort retention labels?
      instructions:
      - text: List all retention labels.
      - text: Show retention labels matching {filter} ordered by {order}.
        slots:
          filter: query.$filter
          order: query.$orderby
      method: generated
      generated: '2026-10-01'
- target: $.paths['/security/labels/retentionLabels'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a retention label
      effect: write
      questions:
      - How do I create a label that keeps content for a set period?
      - Can a retention label delete content after the period ends?
      instructions:
      - text: Create retention label {name} with retention duration {duration}.
        slots:
          name: requestBody.displayName
          duration: requestBody.retentionDuration
      - text: Create label {name} that does {action} after the retention period.
        slots:
          name: requestBody.displayName
          action: requestBody.actionAfterRetentionPeriod
      method: generated
      generated: '2026-10-01'
- target: $.paths['/security/labels/retentionLabels/{retentionLabelId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a retention label
      effect: read
      questions:
      - How long does a specific retention label keep content?
      - Is a particular retention label currently in use?
      instructions:
      - text: Show me retention label {label}.
        slots:
          label: path.retentionLabelId
      - text: Get retention label {label} expanding {expand}.
        slots:
          label: path.retentionLabelId
          expand: query.$expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/security/labels/retentionLabels/{retentionLabelId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a retention label
      effect: destructive
      questions:
      - Can I delete a retention label that is no longer needed?
      - What is the way to remove a retention label?
      instructions:
      - text: Delete retention label {label}.
        slots:
          label: path.retentionLabelId
      - text: Remove label {label} from retention settings.
        slots:
          label: path.retentionLabelId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/security/labels/retentionLabels/{retentionLabelId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a retention label
      effect: write
      questions:
      - How do I change the retention period on an existing label?
      - Can I update the user-facing description of a retention label?
      instructions:
      - text: Change the retention duration of label {label} to {duration}.
        slots:
          label: path.retentionLabelId
          duration: requestBody.retentionDuration
      - text: Set the user description of retention label {label} to {description}.
        slots:
          label: path.retentionLabelId
          description: requestBody.descriptionForUsers
      method: generated
      generated: '2026-10-01'