# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Azure API Management REST Subscription API
  version: 1.0.0
extends: openapi/microsoft-azure-api-management-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: 16
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List all subscriptions on the service
      effect: read
      questions:
      - Which subscriptions exist across my whole API Management service instance?
      - Can I see every product subscription on the service, not just one workspace's?
      instructions:
      - text: List every subscription on my API Management service instance.
      - text: Show me all service-level subscriptions so I can audit who has access.
      - text: List every subscription on the API Management service {serviceName}.
        slots:
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service-level subscription
      effect: read
      questions:
      - How do I look up the details of one subscription on my API Management service?
      - What scope, state and owner does a particular service subscription have?
      instructions:
      - text: Get the service-level subscription with the ID I give you.
      - text: Fetch one subscription's details from the service, not from a workspace.
      - text: Get service-level subscription {sid} from my API Management service {serviceName}.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Subscribe a user to a product
      effect: write
      questions:
      - How do I subscribe a developer to a product on my API Management service?
      - Can I create a new service-level subscription for a user, or overwrite an existing one?
      instructions:
      - text: Create a service-level subscription that gives a user access to a product.
      - text: Create or replace the subscription with the ID I name at the service level.
      - text: Create or replace service-level subscription {sid} on API Management service {serviceName}.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a service-level subscription
      effect: destructive
      questions:
      - How can I remove a developer's subscription from the API Management service?
      - What happens to a service-level subscription's access once I delete it?
      instructions:
      - text: Delete the service-level subscription with the ID I give you.
      - text: Remove this subscription from the service so its keys stop working.
      - text: Delete subscription {sid} from service {serviceName} so its keys stop working.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a service-level subscription
      effect: write
      questions:
      - Can I change just some details of an existing service subscription, like its state or name?
      - Is there a way to patch a subscription on the service without recreating it?
      instructions:
      - text: Patch the existing service-level subscription I name with new details.
      - text: Update the display name or state of a subscription on the service.
      - text: Suspend or reactivate subscription {sid} on service {serviceName} by patching it.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}'].head
  update:
    x-apievangelist-phrasing:
      intent: Get a subscription's ETag version
      effect: read
      questions:
      - Can I read a service subscription's ETag without fetching the full record?
      - What is the current entity version of a subscription before I update it?
      instructions:
      - text: Check the ETag of the service-level subscription I name.
      - text: Confirm a service subscription exists by reading its entity state header only.
      - text: Read just the ETag of service-level subscription {sid} on {serviceName}.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}/listSecrets'].post
  update:
    x-apievangelist-phrasing:
      intent: Show a subscription's keys
      effect: read
      questions:
      - Where do I find the primary and secondary keys for a subscription?
      - Can I retrieve a subscription's key values through the management API?
      instructions:
      - text: Show me the primary and secondary keys of the subscription I name.
      - text: Retrieve the secret keys for this API Management subscription.
      - text: Show the primary and secondary keys of subscription {sid} on service {serviceName}.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}/regeneratePrimaryKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate a subscription's primary key
      effect: destructive
      questions:
      - How do I rotate the primary key on a subscription if it leaked?
      - Will regenerating the primary key leave the secondary key untouched?
      instructions:
      - text: Regenerate the primary key of the subscription I name.
      - text: Rotate this subscription's primary key and invalidate the old one.
      - text: Regenerate the primary key of subscription {sid} on service {serviceName}.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/subscriptions/{sid}/regenerateSecondaryKey'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate a subscription's secondary key
      effect: destructive
      questions:
      - Can I rotate only the secondary key on a subscription while clients use the primary?
      - What do I call to issue a fresh secondary subscription key?
      instructions:
      - text: Regenerate the secondary key of the subscription I name.
      - text: Rotate this subscription's secondary key while keeping the primary in place.
      - text: Regenerate the secondary key of subscription {sid} on service {serviceName}.
        slots:
          sid: path.sid
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/users/{userId}/subscriptions/{sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscription belonging to a user
      effect: read
      questions:
      - How can I look up one subscription through the user who owns it?
      - Which product does a specific user's subscription point to?
      instructions:
      - text: Get the subscription I name from under the user who owns it.
      - text: Look up one of this user's subscriptions by its ID.
      - text: Get subscription {sid} owned by user {userId} on service {serviceName}.
        slots:
          sid: path.sid
          userId: path.userId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/subscriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscriptions in a workspace
      effect: read
      questions:
      - Which subscriptions have been created inside one API Management workspace?
      - Can I list only the subscriptions scoped to a single workspace?
      instructions:
      - text: List every subscription in the workspace I name.
      - text: Show me all workspace-scoped subscriptions for my team's workspace.
      - text: List every subscription in workspace {workspaceId} of service {serviceName}.
        slots:
          workspaceId: path.workspaceId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/subscriptions/{sid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscription in a workspace
      effect: read
      questions:
      - What are the details of one subscription inside a workspace?
      - Can I read a workspace subscription's state and scope by its ID?
      instructions:
      - text: Get the workspace subscription with the ID I give you.
      - text: Fetch one subscription's details from inside my workspace.
      - text: Get subscription {sid} from inside workspace {workspaceId} on {serviceName}.
        slots:
          sid: path.sid
          workspaceId: path.workspaceId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/subscriptions/{sid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Subscribe a user to a workspace product
      effect: write
      questions:
      - How do I subscribe a user to a product that lives in a workspace?
      - Can I create or overwrite a subscription scoped to a single workspace?
      instructions:
      - text: Create a workspace subscription that gives a user access to a workspace product.
      - text: Create or replace the subscription I name inside my workspace.
      - text: Create or replace subscription {sid} inside workspace {workspaceId} on {serviceName}.
        slots:
          sid: path.sid
          workspaceId: path.workspaceId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/subscriptions/{sid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a subscription in a workspace
      effect: destructive
      questions:
      - How can I remove a subscription that belongs to a workspace?
      - Does deleting a workspace subscription cut off that subscriber's keys?
      instructions:
      - text: Delete the workspace subscription with the ID I give you.
      - text: Remove this subscription from my workspace.
      - text: Delete subscription {sid} from workspace {workspaceId} on service {serviceName}.
        slots:
          sid: path.sid
          workspaceId: path.workspaceId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/subscriptions/{sid}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a subscription in a workspace
      effect: write
      questions:
      - Can I patch a workspace subscription's name or state without replacing it?
      - Is it possible to change details on a subscription scoped to a workspace?
      instructions:
      - text: Patch the workspace subscription I name with new details.
      - text: Update the state of a subscription inside my workspace.
      - text: Patch the state of subscription {sid} in workspace {workspaceId} on {serviceName}.
        slots:
          sid: path.sid
          workspaceId: path.workspaceId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/subscriptions/{sid}'].head
  update:
    x-apievangelist-phrasing:
      intent: Get a workspace subscription's ETag
      effect: read
      questions:
      - Can I read the ETag of a workspace subscription without its full body?
      - What entity version does a workspace subscription currently have?
      instructions:
      - text: Check the ETag of the workspace subscription I name.
      - text: Confirm a subscription exists in my workspace using only its entity state.
      - text: Read just the ETag of workspace subscription {sid} in {workspaceId} on {serviceName}.
        slots:
          sid: path.sid
          workspaceId: path.workspaceId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'