# 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 Assets API
  version: 1.0.0
extends: openapi/microsoft-azure-assets-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/workspaces/{workspaceName}/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: Search attack surface assets in an EASM workspace
      effect: read
      questions:
      - How do I find the discovered assets in my Defender EASM workspace?
      - Can I filter and sort workspace assets, for example by state or last seen?
      - What's the page size limit when listing assets in an EASM workspace?
      instructions:
      - text: List assets in EASM workspace {workspaceName} matching filter {filter}.
        slots:
          workspaceName: path.workspaceName
          filter: query.filter
      - text: Show assets from workspace {workspaceName} ordered by {orderby}.
        slots:
          workspaceName: path.workspaceName
          orderby: query.orderby
      - text: Page through workspace {workspaceName} assets, {maxpagesize} per page, skipping {skip}.
        slots:
          workspaceName: path.workspaceName
          maxpagesize: query.maxpagesize
          skip: query.skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/workspaces/{workspaceName}/assets'].patch
  update:
    x-apievangelist-phrasing:
      intent: Relabel workspace assets that match a filter
      effect: write
      questions:
      - Can I apply labels to every asset in my EASM workspace that matches a query?
      - How do I change the state of many attack surface assets at once in a workspace?
      instructions:
      - text: In workspace {workspaceName}, set labels {labels} on assets matching {filter}.
        slots:
          workspaceName: path.workspaceName
          labels: requestBody.labels
          filter: query.filter
      - text: Mark workspace {workspaceName} assets matching {filter} as state {state}.
        slots:
          workspaceName: path.workspaceName
          filter: query.filter
          state: requestBody.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/workspaces/{workspaceName}/assets/{assetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one asset from an EASM workspace
      effect: read
      questions:
      - How can I pull the full record for one asset in my Defender EASM workspace?
      - What details does the workspace return for a single discovered asset?
      instructions:
      - text: Get asset {assetId} from EASM workspace {workspaceName}.
        slots:
          assetId: path.assetId
          workspaceName: path.workspaceName
      - text: Show everything workspace {workspaceName} knows about asset {assetId}.
        slots:
          workspaceName: path.workspaceName
          assetId: path.assetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/workspaces/{workspaceName}/assets/{assetId}/links'].get
  update:
    x-apievangelist-phrasing:
      intent: Get assets linked to an EASM asset
      effect: read
      questions:
      - Which other assets are linked to a given asset in my attack surface?
      - Can I filter the linked-asset details of one EASM asset?
      instructions:
      - text: List assets linked to {assetId} in workspace {workspaceName}.
        slots:
          assetId: path.assetId
          workspaceName: path.workspaceName
      - text: Show linked assets for {assetId} in workspace {workspaceName} matching {filter}.
        slots:
          assetId: path.assetId
          workspaceName: path.workspaceName
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/workspaces/{workspaceName}/assets:export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export matching assets to a datasheet in background
      effect: read
      questions:
      - How do I export my EASM assets to a spreadsheet-style datasheet?
      - Does the asset export run as a background task I can check later?
      instructions:
      - text: Export a datasheet of workspace {workspaceName} assets matching {filter}.
        slots:
          workspaceName: path.workspaceName
          filter: query.filter
      - text: Start a background asset export for EASM workspace {workspaceName}.
        slots:
          workspaceName: path.workspaceName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List attack surface assets from the data plane
      effect: read
      questions:
      - Can I query EASM assets directly from the data-plane endpoint without a workspace path?
      - Which search parameters can I use when listing inventory assets on the data plane?
      instructions:
      - text: List data-plane inventory assets matching filter {filter}.
        slots:
          filter: query.filter
      - text: Fetch inventory assets from the data plane sorted by {orderby}, {maxpagesize} per page.
        slots:
          orderby: query.orderby
          maxpagesize: query.maxpagesize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets'].post
  update:
    x-apievangelist-phrasing:
      intent: Update labels on data-plane assets matching a filter
      effect: write
      questions:
      - How do I bulk-update labels on inventory assets through the data-plane API?
      - Can I transfer or change the state of inventory assets matching a query on the data plane?
      instructions:
      - text: Apply labels {labels} to inventory assets matching {filter} via the data plane.
        slots:
          labels: requestBody.labels
          filter: query.filter
      - text: Set state {state} on every data-plane inventory asset matching {filter}.
        slots:
          state: requestBody.state
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{assetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an inventory asset by ID from the data plane
      effect: read
      questions:
      - What's the data-plane call to fetch one inventory asset by its asset ID?
      - Can I read a single attack surface asset without naming a workspace?
      instructions:
      - text: Get inventory asset {assetId} from the data plane.
        slots:
          assetId: path.assetId
      - text: Retrieve data-plane asset record {assetId}.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.DeviceRegistry/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List Device Registry assets in a subscription
      effect: read
      questions:
      - Which Azure Device Registry assets exist across my whole subscription?
      - Where do I see all industrial asset resources registered in my subscription?
      instructions:
      - text: List all Device Registry assets in my subscription.
      - text: Show every Microsoft.DeviceRegistry asset resource subscription-wide.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DeviceRegistry/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List Device Registry assets in a resource group
      effect: read
      questions:
      - How do I see the Device Registry assets in one resource group?
      - Which asset resources are registered in my current resource group?
      instructions:
      - text: List Device Registry assets in my resource group.
      - text: Show the Microsoft.DeviceRegistry asset resources scoped to this resource group.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DeviceRegistry/assets/{assetName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Device Registry asset
      effect: read
      questions:
      - How can I read the definition of one Device Registry asset?
      - What datapoints and events does a registered asset define?
      instructions:
      - text: Get Device Registry asset {assetName}.
        slots:
          assetName: path.assetName
      - text: Show the configuration of registered asset {assetName}.
        slots:
          assetName: path.assetName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DeviceRegistry/assets/{assetName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a Device Registry asset
      effect: write
      questions:
      - How do I register a new industrial asset in Azure Device Registry?
      - Which extended location does a Device Registry asset need when I create it?
      instructions:
      - text: Create Device Registry asset {assetName} at extended location {extendedLocation}.
        slots:
          assetName: path.assetName
          extendedLocation: requestBody.extendedLocation
      - text: Replace the definition of registered asset {assetName} with properties {properties}.
        slots:
          assetName: path.assetName
          properties: requestBody.properties
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DeviceRegistry/assets/{assetName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Device Registry asset
      effect: destructive
      questions:
      - Can I unregister an asset from Azure Device Registry?
      - What removes a Device Registry asset resource?
      instructions:
      - text: Delete Device Registry asset {assetName}.
        slots:
          assetName: path.assetName
      - text: Unregister asset resource {assetName} from Device Registry.
        slots:
          assetName: path.assetName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DeviceRegistry/assets/{assetName}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a Device Registry asset's tags or properties
      effect: write
      questions:
      - How do I change tags on an existing Device Registry asset?
      - Can I patch only some properties of a registered asset?
      instructions:
      - text: Update tags on Device Registry asset {assetName} to {tags}.
        slots:
          assetName: path.assetName
          tags: requestBody.tags
      - text: Patch properties {properties} on registered asset {assetName}.
        slots:
          properties: requestBody.properties
          assetName: path.assetName
      method: generated
      generated: '2026-09-26'