# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Device Groups API
  version: 1.0.0
extends: openapi/microsoft-azure-device-groups-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: 13
- target: $.paths['/deviceGroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List IoT Central device groups
      effect: read
      questions:
      - Which device groups are defined in my IoT Central application?
      - Can I sort or filter the list of device groups in IoT Central?
      instructions:
      - text: List all device groups in my IoT Central app.
      - text: List IoT Central device groups matching {filter}, ordered by {orderby}.
        slots:
          filter: query.filter
          orderby: query.orderby
      method: generated
      generated: '2026-10-01'
- target: $.paths['/deviceGroups/{deviceGroupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an IoT Central device group
      effect: read
      questions:
      - What filter and organizations does a given IoT Central device group use?
      - Can I look up an IoT Central device group by its ID?
      instructions:
      - text: Show IoT Central device group {group}.
        slots:
          group: path.deviceGroupId
      - text: Get the definition of IoT Central device group {group}.
        slots:
          group: path.deviceGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/deviceGroups/{deviceGroupId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace an IoT Central device group
      effect: write
      questions:
      - How do I create a device group in IoT Central that selects devices by a filter query?
      - Does a new IoT Central device group need a display name and a filter?
      instructions:
      - text: Create IoT Central device group {group} named {name} with filter {filter}.
        slots:
          group: path.deviceGroupId
          name: requestBody.displayName
          filter: requestBody.filter
      - text: Create device group {group} scoped to organizations {orgs}.
        slots:
          group: path.deviceGroupId
          orgs: requestBody.organizations
      method: generated
      generated: '2026-10-01'
- target: $.paths['/deviceGroups/{deviceGroupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an IoT Central device group
      effect: destructive
      questions:
      - Can I delete a device group from my IoT Central application?
      - Is there a way to get rid of an IoT Central device group I no longer need?
      instructions:
      - text: Delete IoT Central device group {group}.
        slots:
          group: path.deviceGroupId
      - text: Remove the device group {group} from IoT Central.
        slots:
          group: path.deviceGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/deviceGroups/{deviceGroupId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing IoT Central device group
      effect: write
      questions:
      - How do I patch an IoT Central device group without recreating it?
      - Can I guard an IoT Central device group update with an ETag?
      instructions:
      - text: Update IoT Central device group {group}.
        slots:
          group: path.deviceGroupId
      - text: Patch IoT Central device group {group} only if its ETag is {etag}.
        slots:
          group: path.deviceGroupId
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/deviceGroups/{deviceGroupId}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List devices in an IoT Central device group
      effect: read
      questions:
      - Which devices currently belong to an IoT Central device group?
      - Can I page through the member devices of a device group?
      instructions:
      - text: List the devices in IoT Central device group {group}.
        slots:
          group: path.deviceGroupId
      - text: Show up to {size} devices per page from device group {group}.
        slots:
          size: query.maxpagesize
          group: path.deviceGroupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/products/{productName}/deviceGroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List Azure Sphere device groups for a product
      effect: read
      questions:
      - Which device groups exist under an Azure Sphere product?
      - Can I filter or page the device groups of a Sphere product?
      instructions:
      - text: List device groups for product {product} in Azure Sphere catalog {catalog}.
        slots:
          product: path.productName
          catalog: path.catalogName
      - text: Show the first {top} Sphere device groups of product {product} in catalog {catalog}.
        slots:
          top: query.$top
          product: path.productName
          catalog: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/products/{productName}/deviceGroups/{deviceGroupName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an Azure Sphere device group
      effect: read
      questions:
      - What are the settings of one Azure Sphere device group?
      - Can I fetch a Sphere device group by catalog, product and group name?
      instructions:
      - text: Get Azure Sphere device group {group} of product {product} in catalog {catalog}.
        slots:
          group: path.deviceGroupName
          product: path.productName
          catalog: path.catalogName
      - text: Show the properties of Sphere device group {group} under {product}.
        slots:
          group: path.deviceGroupName
          product: path.productName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/products/{productName}/deviceGroups/{deviceGroupName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create an Azure Sphere device group
      effect: write
      questions:
      - How do I add a new device group to an Azure Sphere product?
      - Are there reserved names I cannot use for a Sphere device group?
      instructions:
      - text: Create Azure Sphere device group {group} for product {product} in catalog {catalog}.
        slots:
          group: path.deviceGroupName
          product: path.productName
          catalog: path.catalogName
      - text: Create Sphere device group {group} under {product} with properties {props}.
        slots:
          group: path.deviceGroupName
          product: path.productName
          props: requestBody.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/products/{productName}/deviceGroups/{deviceGroupName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an Azure Sphere device group
      effect: destructive
      questions:
      - Can I delete a device group from an Azure Sphere product?
      - Is it possible to remove the system default Sphere device groups?
      instructions:
      - text: Delete Azure Sphere device group {group} of product {product} in catalog {catalog}.
        slots:
          group: path.deviceGroupName
          product: path.productName
          catalog: path.catalogName
      - text: Remove Sphere device group {group} from product {product}.
        slots:
          group: path.deviceGroupName
          product: path.productName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/products/{productName}/deviceGroups/{deviceGroupName}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an Azure Sphere device group
      effect: write
      questions:
      - How do I change the properties of an existing Azure Sphere device group?
      - Can I patch a Sphere device group without recreating it?
      instructions:
      - text: Update Azure Sphere device group {group} of product {product} in catalog {catalog}.
        slots:
          group: path.deviceGroupName
          product: path.productName
          catalog: path.catalogName
      - text: Patch Sphere device group {group} under {product} with properties {props}.
        slots:
          group: path.deviceGroupName
          product: path.productName
          props: requestBody.properties
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/products/{productName}/deviceGroups/{deviceGroupName}/claimDevices'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk claim devices into an Azure Sphere device group
      effect: write
      questions:
      - How do I claim many Azure Sphere devices into a device group at once?
      - Can I bulk claim devices to a catalog only using the unassigned group?
      instructions:
      - text: Claim devices {devices} into Sphere device group {group} of product {product} in catalog {catalog}.
        slots:
          devices: requestBody.deviceIdentifiers
          group: path.deviceGroupName
          product: path.productName
          catalog: path.catalogName
      - text: Bulk claim device IDs {devices} into group {group}.
        slots:
          devices: requestBody.deviceIdentifiers
          group: path.deviceGroupName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.AzureSphere/catalogs/{catalogName}/products/{productName}/deviceGroups/{deviceGroupName}/countDevices'].post
  update:
    x-apievangelist-phrasing:
      intent: Count devices in an Azure Sphere device group
      effect: read
      questions:
      - How many devices are in one of my Azure Sphere device groups?
      - Can I get a device count for a Sphere group without listing every device?
      instructions:
      - text: Count devices in Sphere device group {group} of product {product} in catalog {catalog}.
        slots:
          group: path.deviceGroupName
          product: path.productName
          catalog: path.catalogName
      - text: Tell me how many devices sit in device group {group}.
        slots:
          group: path.deviceGroupName
      method: generated
      generated: '2026-10-01'