# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for WebApps API Client Recommendations API
  version: 1.0.0
extends: openapi/microsoft-azure-functions-recommendations-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: 15
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.Web/recommendations'].get
  update:
    x-apievangelist-phrasing:
      intent: List recommendations for a subscription
      effect: read
      questions:
      - What App Service recommendations does Azure have for my whole subscription?
      - Can I see only the featured recommendations across my subscription?
      instructions:
      - text: List all App Service recommendations for my subscription.
      - text: Show subscription-wide recommendations with featured set to {featured}.
        slots:
          featured: query.featured
      - text: List subscription recommendations matching filter {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.Web/recommendations/{name}/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Turn off a recommendation rule subscription-wide
      effect: write
      questions:
      - How do I stop a specific recommendation rule from applying to my entire subscription?
      - Can I opt my subscription out of one recommendation going forward?
      instructions:
      - text: Disable recommendation rule {name} for my whole subscription.
        slots:
          name: path.name
      - text: Stop rule {name} from being recommended anywhere in this subscription.
        slots:
          name: path.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.Web/recommendations/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset recommendation opt-outs for a subscription
      effect: write
      questions:
      - How do I undo every recommendation opt-out across my subscription?
      - Can I re-enable all the subscription-level rules I previously disabled?
      instructions:
      - text: Reset all recommendation opt-out settings for my subscription.
      - text: Re-enable every recommendation rule I disabled at the subscription level.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/hostingEnvironments/{hostingEnvironmentName}/recommendationHistory'].get
  update:
    x-apievangelist-phrasing:
      intent: Get past recommendations for an ASE
      effect: read
      questions:
      - What recommendations did my App Service Environment receive in the past?
      - Can I see only expired recommendations for a hosting environment within a time range?
      instructions:
      - text: Get the recommendation history for hosting environment {hostingEnvironmentName}.
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
      - text: List expired-only past recommendations for ASE {hostingEnvironmentName} with expiredOnly {expiredOnly}.
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
          expiredOnly: query.expiredOnly
      - text: Show past recommendations for {hostingEnvironmentName} filtered by {filter}.
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/hostingEnvironments/{hostingEnvironmentName}/recommendations'].get
  update:
    x-apievangelist-phrasing:
      intent: List current recommendations for an ASE
      effect: read
      questions:
      - Which recommendations currently apply to my App Service Environment?
      - Are there featured recommendations for a specific hosting environment right now?
      instructions:
      - text: List current recommendations for hosting environment {hostingEnvironmentName}.
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
      - text: Show only featured recommendations for ASE {hostingEnvironmentName} by setting featured to {featured}.
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
          featured: query.featured
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/hostingEnvironments/{hostingEnvironmentName}/recommendations/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a recommendation rule's details for an ASE
      effect: read
      questions:
      - What does a particular recommendation rule say about my hosting environment?
      - Can I mark a hosting environment recommendation as seen when I read it?
      instructions:
      - text: Get details of recommendation rule {name} for hosting environment {hostingEnvironmentName}.
        slots:
          name: path.name
          hostingEnvironmentName: path.hostingEnvironmentName
      - text: Show rule {name} on ASE {hostingEnvironmentName} and mark it seen with updateSeen {updateSeen}.
        slots:
          name: path.name
          hostingEnvironmentName: path.hostingEnvironmentName
          updateSeen: query.updateSeen
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/hostingEnvironments/{hostingEnvironmentName}/recommendations/{name}/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Permanently disable one recommendation for an ASE
      effect: write
      questions:
      - How do I permanently silence a single recommendation rule on my App Service Environment?
      - Can I turn off one recommendation just for a hosting environment instead of the subscription?
      instructions:
      - text: Disable recommendation rule {name} on hosting environment {hostingEnvironmentName} in environment {environmentName}.
        slots:
          name: path.name
          hostingEnvironmentName: path.hostingEnvironmentName
          environmentName: query.environmentName
      - text: Permanently turn off rule {name} for ASE {hostingEnvironmentName} named {environmentName}.
        slots:
          name: path.name
          hostingEnvironmentName: path.hostingEnvironmentName
          environmentName: query.environmentName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/hostingEnvironments/{hostingEnvironmentName}/recommendations/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable all recommendations for an ASE
      effect: write
      questions:
      - How do I switch off every recommendation for one App Service Environment?
      - Can I mute all recommendations at once for a hosting environment?
      instructions:
      - text: Disable all recommendations for hosting environment {hostingEnvironmentName} in environment {environmentName}.
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
          environmentName: query.environmentName
      - text: Mute every recommendation on ASE {hostingEnvironmentName} ({environmentName}).
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
          environmentName: query.environmentName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/hostingEnvironments/{hostingEnvironmentName}/recommendations/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset recommendation opt-outs for an ASE
      effect: write
      questions:
      - How do I re-enable recommendations I opted out of on a hosting environment?
      - Can I clear all recommendation opt-outs for just one App Service Environment?
      instructions:
      - text: Reset all recommendation opt-outs on hosting environment {hostingEnvironmentName} in environment {environmentName}.
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
          environmentName: query.environmentName
      - text: Clear the disabled recommendation rules for ASE {hostingEnvironmentName} ({environmentName}).
        slots:
          hostingEnvironmentName: path.hostingEnvironmentName
          environmentName: query.environmentName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{siteName}/recommendationHistory'].get
  update:
    x-apievangelist-phrasing:
      intent: Get past recommendations for an app
      effect: read
      questions:
      - What recommendations has my web or function app received over time?
      - Can I see only expired recommendations for an app in a given time window?
      instructions:
      - text: Get the recommendation history for app {siteName}.
        slots:
          siteName: path.siteName
      - text: List past recommendations for site {siteName} with expiredOnly {expiredOnly}.
        slots:
          siteName: path.siteName
          expiredOnly: query.expiredOnly
      - text: Narrow the web app recommendation history of site {siteName} using the time-range filter {filter}.
        slots:
          siteName: path.siteName
          filter: query.$filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{siteName}/recommendations'].get
  update:
    x-apievangelist-phrasing:
      intent: List current recommendations for an app
      effect: read
      questions:
      - Which recommendations currently apply to my app?
      - Are there featured recommendations for one of my sites right now?
      instructions:
      - text: List current recommendations for app {siteName}.
        slots:
          siteName: path.siteName
      - text: Show only featured recommendations for site {siteName} with featured {featured}.
        slots:
          siteName: path.siteName
          featured: query.featured
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{siteName}/recommendations/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a recommendation rule's details for an app
      effect: read
      questions:
      - What does one specific recommendation rule say about my app?
      - Can I look up a particular recommendation instance on a site by its ID?
      instructions:
      - text: Get details of recommendation rule {name} for app {siteName}.
        slots:
          name: path.name
          siteName: path.siteName
      - text: Show rule {name} on site {siteName} for recommendation {recommendationId}.
        slots:
          name: path.name
          siteName: path.siteName
          recommendationId: query.recommendationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{siteName}/recommendations/{name}/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Permanently disable one recommendation for an app
      effect: write
      questions:
      - How do I permanently stop one recommendation from showing for my app?
      - Can I turn off a single rule for just one web site?
      instructions:
      - text: Disable recommendation rule {name} for app {siteName}.
        slots:
          name: path.name
          siteName: path.siteName
      - text: Permanently turn off rule {name} on site {siteName}.
        slots:
          name: path.name
          siteName: path.siteName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{siteName}/recommendations/disable'].post
  update:
    x-apievangelist-phrasing:
      intent: Disable all recommendations for an app
      effect: write
      questions:
      - How do I switch off every recommendation for one of my apps?
      - Can I mute all recommendations for a single site at once?
      instructions:
      - text: Disable all recommendations for app {siteName}.
        slots:
          siteName: path.siteName
      - text: Mute every recommendation on site {siteName}.
        slots:
          siteName: path.siteName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{siteName}/recommendations/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset recommendation opt-outs for an app
      effect: write
      questions:
      - How do I bring back recommendations I disabled for my app?
      - Can I clear all recommendation opt-outs on one site?
      instructions:
      - text: Reset all recommendation opt-outs for app {siteName}.
        slots:
          siteName: path.siteName
      - text: Clear the disabled recommendation rules on site {siteName}.
        slots:
          siteName: path.siteName
      method: generated
      generated: '2026-10-01'