API Evangelist conversational phrasing for Azure API Management REST Subscriptions API

# 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 Subscriptions API
  version: 1.0.0
extends: openapi/microsoft-azure-api-management-subscriptions-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: 12
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis'].get
  update:
    x-apievangelist-phrasing:
      intent: List all APIs in an API Management service
      effect: read
      questions:
      - What APIs are published in my API Management instance?
      - Can I get a list of every API across the whole service, not just one workspace?
      instructions:
      - text: List all APIs in my API Management service.
      - text: Show every API registered at the service level.
      - text: List all APIs registered on 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}/apis/{apiId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service-level API's details
      effect: read
      questions:
      - How do I see the path, protocols and settings of one API in APIM?
      - Where can I look up a single API's configuration by its identifier?
      instructions:
      - text: Get the details of this API in my API Management service.
      - text: Show the service-level API definition by its ID.
      - text: Get the service-level API definition {apiId} from service {serviceName}.
        slots:
          apiId: path.apiId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace an API in the service
      effect: write
      questions:
      - How do I add a new API to my API Management instance?
      - Can I import or overwrite an existing API definition at the service level?
      instructions:
      - text: Create an API in my API Management service with {properties}.
        slots:
          properties: requestBody.properties
      - text: Create or replace this service-level API.
      - text: Create or replace service-level API {apiId} on API Management service {serviceName}.
        slots:
          apiId: path.apiId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an API from the service
      effect: destructive
      questions:
      - Can I remove an API from API Management once it's retired?
      - Does deleting a service-level API also remove its operations?
      instructions:
      - text: Delete this API from my API Management service.
      - text: Remove the retired service-level API.
      - text: Delete service-level API {apiId} from API Management service {serviceName}.
        slots:
          apiId: path.apiId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing API in the service
      effect: write
      questions:
      - Can I change only a few properties on an API that already exists in APIM?
      - Is there a way to patch an API's display name or path without redefining it?
      instructions:
      - text: Update my existing service-level API with {properties}.
        slots:
          properties: requestBody.properties
      - text: Patch the settings of this API in the API Management service.
      - text: Patch the settings of existing API {apiId} on service {serviceName}.
        slots:
          apiId: path.apiId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check a service-level API's ETag
      effect: read
      questions:
      - How do I fetch an API's current ETag before I update it?
      - Can I confirm a service-level API exists with a HEAD request?
      instructions:
      - text: Get the entity tag version of this API.
      - text: Check the ETag for the service-level API.
      - text: Read only the ETag of service-level API {apiId} on {serviceName}.
        slots:
          apiId: path.apiId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/workspaces/{workspaceId}/apis'].get
  update:
    x-apievangelist-phrasing:
      intent: List the APIs in a workspace
      effect: read
      questions:
      - Which APIs belong to one workspace in my API Management instance?
      - Can I scope the API list to a single workspace team?
      instructions:
      - text: List the APIs in this workspace.
      - text: Show the APIs a workspace owns.
      - text: List the APIs owned by workspace {workspaceId} on 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}/apis/{apiId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an API inside a workspace
      effect: read
      questions:
      - How do I view the details of an API that lives in a workspace?
      - What configuration does a workspace-scoped API have?
      instructions:
      - text: Get this workspace API by its identifier.
      - text: Show me the API definition from the workspace.
      - text: Get API {apiId} from workspace {workspaceId} on service {serviceName}.
        slots:
          apiId: path.apiId
          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}/apis/{apiId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace an API in a workspace
      effect: write
      questions:
      - Can a workspace team publish its own API in API Management?
      - How do I add an API that only belongs to one workspace?
      instructions:
      - text: Create a new API inside my workspace.
      - text: Create or overwrite this API at workspace scope.
      - text: Create or overwrite API {apiId} inside workspace {workspaceId} on {serviceName}.
        slots:
          apiId: path.apiId
          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}/apis/{apiId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an API from a workspace
      effect: destructive
      questions:
      - Can I delete an API that belongs to a workspace?
      - Will removing a workspace API affect APIs at the service level?
      instructions:
      - text: Delete this API from the workspace.
      - text: Remove the workspace-scoped API.
      - text: Delete API {apiId} from workspace {workspaceId} on service {serviceName}.
        slots:
          apiId: path.apiId
          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}/apis/{apiId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an API in a workspace
      effect: write
      questions:
      - Can I patch a few fields on an API owned by a workspace?
      - Is a partial update supported for workspace APIs?
      instructions:
      - text: Update the workspace API's settings.
      - text: Patch this API inside my APIM workspace.
      - text: Patch the settings of API {apiId} in workspace {workspaceId} on {serviceName}.
        slots:
          apiId: path.apiId
          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}/apis/{apiId}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check a workspace API's ETag
      effect: read
      questions:
      - How do I read the ETag of an API in a workspace?
      - Is there a quick existence check for a workspace-scoped API?
      instructions:
      - text: Get the entity tag of this workspace API.
      - text: Check whether the workspace API exists and return its ETag.
      - text: Read only the ETag of workspace API {apiId} in {workspaceId} on {serviceName}.
        slots:
          apiId: path.apiId
          workspaceId: path.workspaceId
          serviceName: path.serviceName
      method: generated
      generated: '2026-10-01'