# 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 API Management Service API
  version: 1.0.0
extends: openapi/microsoft-azure-api-management-apimanagementservice-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 13
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/checkNameAvailability'].post
  update:
    x-apievangelist-phrasing:
      intent: Check if an API Management service name is free
      effect: read
      questions:
      - Is the name I want for a new Azure API Management service already taken?
      - Can I check whether a service name is valid before I try to create the instance?
      instructions:
      - text: Check whether {name} is available as an API Management service name.
        slots:
          name: requestBody.name
      - text: Tell me if the service name {name} is valid and unclaimed.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/getDomainOwnershipIdentifier'].post
  update:
    x-apievangelist-phrasing:
      intent: Get the custom domain ownership identifier
      effect: read
      questions:
      - Where do I find the ownership identifier to prove I own a custom domain for API Management?
      - What value goes in the DNS TXT record when verifying a custom domain for my gateway?
      instructions:
      - text: Get the custom domain ownership identifier for my subscription.
      - text: Fetch the domain ownership ID I need to verify a custom hostname.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.ApiManagement/service'].get
  update:
    x-apievangelist-phrasing:
      intent: List all API Management services in a subscription
      effect: read
      questions:
      - Which API Management instances exist across my whole Azure subscription?
      - Can I see every APIM service I own without going resource group by resource group?
      instructions:
      - text: List every API Management service in my Azure subscription.
      - text: Show all APIM instances across the subscription.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service'].get
  update:
    x-apievangelist-phrasing:
      intent: List API Management services in a resource group
      effect: read
      questions:
      - What API Management instances live in one particular resource group?
      - Can I narrow the list of APIM services down to a single resource group?
      instructions:
      - text: List the API Management services inside this resource group.
      - text: Show only the APIM instances deployed to my resource group.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an API Management service's details
      effect: read
      questions:
      - How do I look up the configuration of one API Management instance?
      - What SKU, location and settings does my APIM service currently have?
      instructions:
      - text: Get the full description of my API Management service.
      - text: Show the current settings of this APIM instance.
      - text: Get the full description and settings of 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}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace an API Management service
      effect: write
      questions:
      - How do I provision a new Azure API Management instance?
      - How long does creating an API Management service take, and is it asynchronous?
      - Can I choose the region and pricing tier when I create an APIM instance?
      instructions:
      - text: Create an API Management service named {name} in {location} on the {sku} tier.
        slots:
          name: requestBody.name
          location: requestBody.location
          sku: requestBody.sku
      - text: Provision a new APIM instance in region {location}.
        slots:
          location: requestBody.location
      - text: Recreate my API Management service with a full new definition.
      - text: Provision or redefine the APIM instance {serviceName} in its resource group.
        slots:
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an API Management service
      effect: destructive
      questions:
      - Can I tear down an API Management instance I no longer use?
      - What happens to my APIs when I delete the whole APIM service?
      instructions:
      - text: Delete this API Management service.
      - text: Remove the APIM instance from my resource group entirely.
      - text: Delete API Management service {serviceName} from my resource group entirely.
        slots:
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update settings on an existing API Management service
      effect: write
      questions:
      - Can I change the pricing tier of an API Management instance that already exists?
      - Is there a way to patch just a few properties of my APIM service?
      instructions:
      - text: Change the SKU of my existing API Management service to {sku}.
        slots:
          sku: requestBody.sku
      - text: Patch the properties of my running APIM instance with {properties}.
        slots:
          properties: requestBody.properties
      - text: Patch the properties of my running 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}/applynetworkconfigurationupdates'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply updated DNS settings in a virtual network
      effect: write
      questions:
      - My APIM instance runs in a virtual network and I changed DNS -- how do I make it pick that up?
      - Does API Management refresh virtual network DNS changes on its own?
      instructions:
      - text: Apply the pending network configuration updates to my API Management service.
      - text: Make my VNet-injected APIM instance pick up the new DNS settings.
      - text: Apply pending network configuration updates to 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}/backup'].post
  update:
    x-apievangelist-phrasing:
      intent: Back up an API Management service to storage
      effect: write
      questions:
      - How do I back up my API Management configuration to an Azure Storage account?
      - Is backing up an APIM service a long-running operation?
      instructions:
      - text: Back up my API Management service to the storage account.
      - text: Create a backup of this APIM instance's configuration.
      - text: Back up the configuration of API Management service {serviceName} to storage.
        slots:
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/getssotoken'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a single sign-on token for the service
      effect: read
      questions:
      - How can I get a single sign-on token to open the API Management publisher experience?
      - How long is an API Management SSO token valid?
      instructions:
      - text: Get a single sign-on token for my API Management service.
      - text: Issue me a five-minute SSO token for this APIM instance.
      - text: Get a single sign-on token, valid five minutes, for APIM instance {serviceName}.
        slots:
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-02'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/migrateToStv2'].post
  update:
    x-apievangelist-phrasing:
      intent: Migrate an API Management service to stv2
      effect: destructive
      questions:
      - How do I move my API Management instance onto the stv2 compute platform?
      - Can I roll back after upgrading an APIM service to stv2?
      instructions:
      - text: Migrate my API Management service to the stv2 platform.
      - text: Upgrade this APIM instance to stv2, knowing it cannot be reversed.
      - text: Start the long-running Stv2 platform upgrade for APIM instance {serviceName}.
        slots:
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-02'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore an API Management service from a backup
      effect: write
      questions:
      - Can I restore my APIM instance from a backup I took earlier?
      - What does restoring an API Management backup overwrite on the current service?
      instructions:
      - text: Restore my API Management service from its saved backup.
      - text: Roll this APIM instance back to the configuration in the storage backup.
      - text: Restore API Management service {serviceName} from its saved storage backup.
        slots:
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'