# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenAPI definition Discovery and Exposure Management API
  version: 1.0.0
extends: openapi/palo-alto-networks-discovery-and-exposure-management-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: 26
- target: $.paths['/asm/api/v1/convert-cloud-account'].post
  update:
    x-apievangelist-phrasing:
      intent: Onboard unmanaged cloud accounts to CSPM
      effect: write
      questions:
      - How do I bring cloud accounts found by exposure discovery under CSPM protection?
      - Can I convert several unmanaged cloud accounts to managed ones in one request?
      instructions:
      - text: Onboard cloud accounts {cloudAccounts} to CSPM so their unmanaged assets get secured.
        slots:
          cloudAccounts: requestBody.cloudAccounts
      - text: Convert the unmanaged cloud accounts from the exposure dashboard into CSPM-managed accounts.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset'].post
  update:
    x-apievangelist-phrasing:
      intent: List discovered assets with filters
      effect: read
      questions:
      - Which internet-exposed assets were discovered in my AWS and Azure clouds?
      - Can I filter the discovered asset inventory by managed versus unmanaged and service type?
      - What assets match a search text in the exposure management inventory?
      instructions:
      - text: List discovered assets of cloud type {cloudTypes} and asset type {assetTypes}.
        slots:
          cloudTypes: requestBody.cloudTypes
          assetTypes: requestBody.assetTypes
      - text: Search the asset inventory for {searchText} as of snapshot {snapshotDate}.
        slots:
          searchText: requestBody.searchText
          snapshotDate: requestBody.snapshotDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/{asset_id}/finding'].post
  update:
    x-apievangelist-phrasing:
      intent: Get security findings for an asset
      effect: read
      questions:
      - What security findings and vulnerabilities were discovered on a specific asset?
      - Can I narrow an asset's findings to only critical and high severities?
      instructions:
      - text: Show the security findings for asset {asset_id}.
        slots:
          asset_id: path.asset_id
      - text: List findings on asset {asset_id} with severity {severities}.
        slots:
          asset_id: path.asset_id
          severities: requestBody.severities
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/{asset_id}/finding/filters'].post
  update:
    x-apievangelist-phrasing:
      intent: Get the filter values for an asset's findings
      effect: read
      questions:
      - Which finding types and severities can I filter on for a particular asset?
      - What filter values are available before I pull an asset's findings?
      instructions:
      - text: Get the available finding filters and their values for asset {asset_id}.
        slots:
          asset_id: path.asset_id
      - text: Show which finding filter options exist for asset {asset_id} on snapshot {snapshotDate}.
        slots:
          asset_id: path.asset_id
          snapshotDate: requestBody.snapshotDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/snooze'].post
  update:
    x-apievangelist-phrasing:
      intent: Snooze notifications for unmanaged assets
      effect: write
      questions:
      - How do I silence alerts from unmanaged internet-exposed assets for a while?
      - Can I snooze every asset matching a regex pattern permanently?
      instructions:
      - text: Snooze notifications for unmanaged assets {assets} because {reason}.
        slots:
          assets: requestBody.assets
          reason: requestBody.reason
      - text: Snooze all unmanaged assets matching regex {regex} for time range {snoozeTimeRange}.
        slots:
          regex: requestBody.regex
          snoozeTimeRange: requestBody.snoozeTimeRange
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/reopen'].post
  update:
    x-apievangelist-phrasing:
      intent: Unsnooze snoozed unmanaged assets
      effect: write
      questions:
      - How do I turn notifications back on for assets I previously snoozed?
      - Can I reopen snoozed assets that match a regex pattern?
      instructions:
      - text: Unsnooze the snoozed assets {assets}.
        slots:
          assets: requestBody.assets
      - text: Reopen every snoozed asset matching regex {regex}.
        slots:
          regex: requestBody.regex
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/email'].post
  update:
    x-apievangelist-phrasing:
      intent: Email asset details to colleagues
      effect: write
      questions:
      - Can I email the details of an exposed asset to my team?
      - How do I share an unmanaged asset's details by email with a comment?
      instructions:
      - text: Email the details of asset {asmAssetId} to {userEmailIds}.
        slots:
          asmAssetId: requestBody.asmAssetId
          userEmailIds: requestBody.userEmailIds
      - text: Send asset {name} details to {userEmailIds} with the note {comment}.
        slots:
          name: requestBody.name
          userEmailIds: requestBody.userEmailIds
          comment: requestBody.comment
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/download'].post
  update:
    x-apievangelist-phrasing:
      intent: Download a filtered list of unmanaged assets
      effect: read
      questions:
      - Can I export the list of unmanaged assets to a file?
      - How do I download only the unmanaged assets from one cloud provider?
      instructions:
      - text: Download the unmanaged asset list for cloud type {cloudTypes}.
        slots:
          cloudTypes: requestBody.cloudTypes
      - text: Export unmanaged assets of service type {serviceTypes} as of {snapshotDate}.
        slots:
          serviceTypes: requestBody.serviceTypes
          snapshotDate: requestBody.snapshotDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/aggregation-by-resource-type'].post
  update:
    x-apievangelist-phrasing:
      intent: Count assets grouped by asset type
      effect: read
      questions:
      - How many discovered assets do I have of each asset type?
      - What is the breakdown of asset counts per resource type for one cloud?
      instructions:
      - text: Count assets by asset type for cloud type {cloudTypes}.
        slots:
          cloudTypes: requestBody.cloudTypes
      - text: Give me the per-asset-type asset totals for manage type {manageType}.
        slots:
          manageType: requestBody.manageType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/aggregation-by-cloud-type'].post
  update:
    x-apievangelist-phrasing:
      intent: Count assets grouped by cloud provider
      effect: read
      questions:
      - How many discovered assets sit in each cloud service provider?
      - Which cloud provider holds the most unmanaged assets?
      instructions:
      - text: Count assets per cloud provider for snapshot {snapshotDate}.
        slots:
          snapshotDate: requestBody.snapshotDate
      - text: Break down asset totals by cloud provider for manage type {manageType}.
        slots:
          manageType: requestBody.manageType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/service'].get
  update:
    x-apievangelist-phrasing:
      intent: List discovered exposed services
      effect: read
      questions:
      - What exposed services has attack surface discovery found across my environment?
      - Can I list discovered services as of a past snapshot date?
      instructions:
      - text: List all discovered services.
      - text: List discovered services for snapshot date {snapshot_date}.
        slots:
          snapshot_date: query.snapshot_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/service/{serviceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a discovered service
      effect: read
      questions:
      - What are the details of one specific discovered service?
      - Can I get the full detail record for a service by its id?
      instructions:
      - text: Show details for service {serviceId}.
        slots:
          serviceId: path.serviceId
      - text: Get service {serviceId} as it looked on {snapshot_date}.
        slots:
          serviceId: path.serviceId
          snapshot_date: query.snapshot_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/industry-benchmarks'].get
  update:
    x-apievangelist-phrasing:
      intent: Get industry benchmark data
      effect: read
      questions:
      - How does my exposure compare against industry benchmark data?
      - What industry benchmarks does Palo Alto Networks use to judge vulnerability risk?
      instructions:
      - text: Fetch the industry benchmark data for exposure risk.
      - text: Show me the industry benchmarks used to score security risks.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/dashboard/convertible-accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List cloud accounts that can be onboarded to CSPM
      effect: read
      questions:
      - Which cloud accounts are not yet managed by CSPM but could be onboarded?
      - Can I filter convertible cloud accounts by country?
      instructions:
      - text: List cloud accounts eligible for CSPM onboarding.
      - text: Show convertible cloud accounts in country {country_code} with alert category {alert_categories}.
        slots:
          country_code: query.country_code
          alert_categories: query.alert_categories
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/dashboard/asset'].get
  update:
    x-apievangelist-phrasing:
      intent: List unmanaged assets that can be onboarded
      effect: read
      questions:
      - Which unmanaged assets could I bring under CSPM management?
      - What convertible assets belong to one particular cloud account?
      instructions:
      - text: List convertible unmanaged assets in cloud account {cloud_account_id}.
        slots:
          cloud_account_id: query.cloud_account_id
      - text: Show onboardable assets located in country {country_code}.
        slots:
          country_code: query.country_code
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/dashboard/asset/trend'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the 90-day managed versus unmanaged asset trend
      effect: read
      questions:
      - How have my managed, unmanaged and remediated asset counts trended over 90 days?
      - Is the number of unmanaged assets going down over the last quarter?
      instructions:
      - text: Show the 90-day asset trend ending at {timestamp}.
        slots:
          timestamp: query.timestamp
      - text: Chart managed versus remediated assets over the last 90 days from {timestamp}.
        slots:
          timestamp: query.timestamp
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/dashboard/asset/top-risk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the top risks across assets
      effect: read
      questions:
      - What are the biggest risks across my discovered assets right now?
      - Which asset risks rank highest on the exposure dashboard?
      instructions:
      - text: List the top asset risks.
      - text: Show me the highest-ranked risks from the asset dashboard.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/dashboard/asset/internet-exposure-risk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get internet exposure risk by asset type
      effect: read
      questions:
      - How is internet exposure risk distributed across asset types in the last day?
      - Which asset types carried the most internet exposure risk over the past 24 hours?
      instructions:
      - text: Show the internet exposure risk distribution per asset type for the last 24 hours.
      - text: Get today's internet exposure risk statistics for every asset type.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/dashboard/asset/geolocation'].get
  update:
    x-apievangelist-phrasing:
      intent: Count assets by geographic location
      effect: read
      questions:
      - Where in the world are my discovered assets located?
      - How many assets do I have in each geographic location?
      instructions:
      - text: Count my assets by geolocation.
      - text: Show the asset distribution across locations on a map.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/dashboard/asset/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count assets that can be onboarded
      effect: read
      questions:
      - How many unmanaged assets are convertible to CSPM in total?
      - What is the total number of onboardable assets?
      instructions:
      - text: Get the total count of convertible assets.
      - text: Tell me how many assets are ready to onboard to CSPM.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/{asset_id}/vulnerability'].get
  update:
    x-apievangelist-phrasing:
      intent: List vulnerabilities in an asset
      effect: read
      questions:
      - What vulnerabilities exist in one asset on a given snapshot date?
      - Can I see the CVEs behind the top risks widget for an unmanaged asset?
      instructions:
      - text: List vulnerabilities in asset {asset_id} on {snapshot_date}.
        slots:
          asset_id: path.asset_id
          snapshot_date: query.snapshot_date
      - text: Show vulnerabilities for {manage_type} asset {asset_id} as of {snapshot_date}.
        slots:
          manage_type: query.manage_type
          asset_id: path.asset_id
          snapshot_date: query.snapshot_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/{assetId}/flowlog-relationships'].get
  update:
    x-apievangelist-phrasing:
      intent: Get traffic flows between unmanaged and managed assets
      effect: read
      questions:
      - Is an internet-exposed unmanaged asset talking to any of my secured assets?
      - Can I see flow log traffic between an unmanaged asset and managed ones?
      instructions:
      - text: Show flow log relationships for unmanaged asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Get traffic flows for asset {assetId} on {snapshot_date}.
        slots:
          assetId: path.assetId
          snapshot_date: query.snapshot_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/{asmAssetId}/service'].get
  update:
    x-apievangelist-phrasing:
      intent: List services running on an asset
      effect: read
      questions:
      - Which services are linked to a specific discovered asset?
      - What exposed services does one asset run on a given snapshot?
      instructions:
      - text: List services for asset {asmAssetId} on {snapshot_date}.
        slots:
          asmAssetId: path.asmAssetId
          snapshot_date: query.snapshot_date
      - text: Show what services asset {asmAssetId} exposed as of {snapshot_date}.
        slots:
          asmAssetId: path.asmAssetId
          snapshot_date: query.snapshot_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/vulnerability'].get
  update:
    x-apievangelist-phrasing:
      intent: Find distros and packages affected by a CVE
      effect: read
      questions:
      - Which Linux distributions and packages are impacted by a given CVE?
      - Can I look up affected distros for a vulnerability by its CVE ID?
      instructions:
      - text: List distros and packages impacted by {cve_id}.
        slots:
          cve_id: query.cve_id
      - text: Look up which distributions are affected by vulnerability {cve_id}.
        slots:
          cve_id: query.cve_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/snoozed-regex'].get
  update:
    x-apievangelist-phrasing:
      intent: List regex patterns used to snooze assets
      effect: read
      questions:
      - What regex patterns are currently being used to snooze assets?
      - Which snooze patterns did we set up for unmanaged assets?
      instructions:
      - text: List the regex patterns used for snoozing assets.
      - text: Show all asset snooze regex patterns.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asm/api/v1/asset/filters'].get
  update:
    x-apievangelist-phrasing:
      intent: List supported asset filters and values
      effect: read
      questions:
      - Which filters and values can I use when querying the asset inventory?
      - What cloud types and asset types are valid asset filter values?
      instructions:
      - text: List the supported asset filters and their values.
      - text: Show the filter options I can pass to the asset list endpoints.
      method: generated
      generated: '2026-09-26'