# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for ChangeNotifications Subscriptions.subscription API
  version: 1.0.0
extends: openapi/azure-ad-subscriptions-subscription-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['/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List change notification subscriptions
      effect: read
      questions:
      - Which webhook subscriptions for change notifications are active for my app?
      - Can I see when each of my Microsoft Graph change notification subscriptions expires?
      instructions:
      - text: List my change notification subscriptions.
      - text: Show all active webhook subscriptions and their expiry times.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe to change notifications on a resource
      effect: write
      questions:
      - How do I get notified at my webhook when users or groups change?
      - Can I include resource data in change notifications if I supply an encryption certificate?
      - What change types can a new notification subscription listen for?
      instructions:
      - text: Subscribe {url} to {change_type} changes on {resource} until {expires}.
        slots:
          url: requestBody.notificationUrl
          change_type: requestBody.changeType
          resource: requestBody.resource
          expires: requestBody.expirationDateTime
      - text: Create a change notification subscription on {resource} delivering to {url}.
        slots:
          resource: requestBody.resource
          url: requestBody.notificationUrl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscription-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one change notification subscription
      effect: read
      questions:
      - What resource and notification URL is a specific subscription set up for?
      - When does one particular change notification subscription expire?
      instructions:
      - text: Get change notification subscription {subscription}.
        slots:
          subscription: path.subscription-id
      - text: Show the expiry and notification URL of subscription {subscription}.
        slots:
          subscription: path.subscription-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscription-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop a change notification subscription
      effect: destructive
      questions:
      - How do I stop receiving change notifications for a subscription?
      - Can I cancel a webhook subscription before it expires?
      instructions:
      - text: Delete change notification subscription {subscription}.
        slots:
          subscription: path.subscription-id
      - text: Unsubscribe and stop notifications for {subscription}.
        slots:
          subscription: path.subscription-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscription-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Renew a change notification subscription
      effect: write
      questions:
      - How do I renew a change notification subscription before it expires?
      - Can I extend a webhook subscription's expiry time instead of recreating it?
      instructions:
      - text: Renew subscription {subscription} until {expires}.
        slots:
          subscription: path.subscription-id
          expires: requestBody.expirationDateTime
      - text: Extend the expiry of webhook subscription {subscription} to {expires}.
        slots:
          subscription: path.subscription-id
          expires: requestBody.expirationDateTime
      method: generated
      generated: '2026-10-01'