# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for HERE WeGo User Service Subscriptions API
  version: 1.0.0
extends: openapi/here-subscriptions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 15
- target: $.paths['/subscriptions/{subscriptionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription by its ID
      effect: write
      questions:
      - How do I link a subscription to its Zuora billing subscription using the subscription ID?
      - Can I update a subscription when I have its ID rather than its key?
      instructions:
      - text: Update subscription ID {subscriptionId} to use Zuora subscription {zuoraSubscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
          zuoraSubscriptionId: requestBody.zuoraSubscriptionId
      - text: Change the details of subscription with ID {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a subscription by its key
      effect: read
      questions:
      - How do I get subscription details if I only have the subscription key?
      - Which feature groups are on the subscription behind a given key?
      instructions:
      - text: Get the subscription for key {subscriptionKey}.
        slots:
          subscriptionKey: path.subscriptionKey
      - text: Show details of the subscription identified by key {subscriptionKey}.
        slots:
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription by its key
      effect: write
      questions:
      - Can I update a subscription's Zuora link using the subscription key instead of the ID?
      - How do I edit a subscription when all I have is its key?
      instructions:
      - text: Set Zuora subscription {zuoraSubscriptionId} on the subscription with key {subscriptionKey}.
        slots:
          zuoraSubscriptionId: requestBody.zuoraSubscriptionId
          subscriptionKey: path.subscriptionKey
      - text: Update the subscription behind key {subscriptionKey}.
        slots:
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List an organization's active subscriptions
      effect: read
      questions:
      - Which subscriptions are currently active for my organization?
      - Can I page through active subscriptions in smaller batches?
      instructions:
      - text: List my organization's active subscriptions.
      - text: Show page {page} of active subscriptions, {size} per page.
        slots:
          page: query.page
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create new subscription keys
      effect: write
      questions:
      - How do I generate a batch of new subscription keys with certain feature groups?
      - Can I set an expiration time when creating subscription keys?
      instructions:
      - text: Create {numKeys} subscription keys of type {keyType} with feature groups {featureGroups}.
        slots:
          numKeys: requestBody.numKeys
          keyType: requestBody.keyType
          featureGroups: requestBody.featureGroups
      - text: Generate {numKeys} {keyType} keys for feature groups {featureGroups} that expire at {expirationTime}.
        slots:
          numKeys: requestBody.numKeys
          keyType: requestBody.keyType
          featureGroups: requestBody.featureGroups
          expirationTime: requestBody.expirationTime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/featureGroups/{featureGroupId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a feature group to a subscription by ID
      effect: write
      questions:
      - How do I add a feature group to a subscription using its subscription ID and feature group ID?
      - Can I enable extra features on a subscription I reference by ID?
      instructions:
      - text: Add feature group {featureGroupId} to subscription ID {subscriptionId}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionId: path.subscriptionId
      - text: Attach feature group ID {featureGroupId} to the subscription whose ID is {subscriptionId}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/featureGroups/{featureGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a feature group from a subscription by ID
      effect: destructive
      questions:
      - How do I take a feature group off a subscription when I have the subscription ID?
      - Can I drop one feature group from a subscription referenced by ID without cancelling it?
      instructions:
      - text: Remove feature group {featureGroupId} from subscription ID {subscriptionId}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionId: path.subscriptionId
      - text: Detach feature group ID {featureGroupId} from the subscription with ID {subscriptionId}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionId: path.subscriptionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}/featureGroups/{featureGroupId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a feature group to a subscription by key
      effect: write
      questions:
      - Can I add a feature group by its ID to a subscription I only know by key?
      - How do I enable a feature group ID on a subscription key?
      instructions:
      - text: Add feature group ID {featureGroupId} to the subscription with key {subscriptionKey}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionKey: path.subscriptionKey
      - text: Attach feature group {featureGroupId} to subscription key {subscriptionKey}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}/featureGroups/{featureGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a feature group from a subscription by key
      effect: destructive
      questions:
      - How do I remove a feature group ID from a subscription identified by its key?
      - Can I revoke one feature group ID from a subscription key?
      instructions:
      - text: Using subscription key {subscriptionKey}, drop feature group ID {featureGroupId}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionKey: path.subscriptionKey
      - text: Detach feature group {featureGroupId} from the subscription with key {subscriptionKey}.
        slots:
          featureGroupId: path.featureGroupId
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}/featureGroups/names/{featureGroupName}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a feature group by name to a subscription key
      effect: write
      questions:
      - Can I add a feature group to a subscription key using the feature group's name instead of its ID?
      - How do I enable a named feature group on a subscription?
      instructions:
      - text: Add the feature group named {featureGroupName} to subscription key {subscriptionKey}.
        slots:
          featureGroupName: path.featureGroupName
          subscriptionKey: path.subscriptionKey
      - text: Enable feature group name {featureGroupName} on the subscription with key {subscriptionKey}.
        slots:
          featureGroupName: path.featureGroupName
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}/featureGroups/names/{featureGroupName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a feature group by name from a subscription key
      effect: destructive
      questions:
      - How do I remove a feature group from a subscription key by the group's name?
      - Can I drop a named feature group without knowing its ID?
      instructions:
      - text: Remove the feature group named {featureGroupName} from subscription key {subscriptionKey}.
        slots:
          featureGroupName: path.featureGroupName
          subscriptionKey: path.subscriptionKey
      - text: Disable feature group name {featureGroupName} on the subscription with key {subscriptionKey}.
        slots:
          featureGroupName: path.featureGroupName
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Deactivate specific devices on a subscription
      effect: destructive
      questions:
      - How do I deactivate particular devices tied to a subscription key?
      - Can I turn off just some devices on a subscription without deactivating the whole subscription?
      instructions:
      - text: Deactivate devices {devices} on subscription key {subscriptionKey}.
        slots:
          devices: requestBody.devices
          subscriptionKey: path.subscriptionKey
      - text: Turn off the listed devices {devices} for the subscription with key {subscriptionKey}.
        slots:
          devices: requestBody.devices
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a subscription
      effect: destructive
      questions:
      - How do I deactivate an entire subscription?
      - What happens when I set a subscription's status to deactivated?
      instructions:
      - text: Deactivate the subscription for key {subscriptionKey}.
        slots:
          subscriptionKey: header.x-subscription-key
      - text: Set the subscription with key {subscriptionKey} to status {status}.
        slots:
          subscriptionKey: header.x-subscription-key
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/keys/{subscriptionKey}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List devices on a subscription
      effect: read
      questions:
      - Which devices are registered against a subscription key?
      - How can I see the device details attached to a subscription?
      instructions:
      - text: List the devices on subscription key {subscriptionKey}.
        slots:
          subscriptionKey: path.subscriptionKey
      - text: Show device details for the subscription with key {subscriptionKey}.
        slots:
          subscriptionKey: path.subscriptionKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/devices'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all devices on a subscription
      effect: destructive
      questions:
      - How do I wipe every device associated with a subscription key?
      - Can I clear all registered devices from a subscription at once?
      instructions:
      - text: Delete all devices associated with subscription key {subscriptionKey}.
        slots:
          subscriptionKey: header.x-subscription-key
      - text: Clear every registered device from the subscription with key {subscriptionKey}.
        slots:
          subscriptionKey: header.x-subscription-key
      method: generated
      generated: '2026-09-26'