# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Assets API
  version: 1.0.0
extends: openapi/drata-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: 5
- target: $.paths['/assets'].get
  update:
    x-apievangelist-phrasing:
      intent: List assets
      effect: read
      questions:
      - Which assets are assigned to a given user?
      - Can I filter the asset inventory by type or provider?
      instructions:
      - text: List assets of type {assetType}.
        slots:
          assetType: query.assetType
      - text: List assets associated with user {userId}.
        slots:
          userId: query.userId
      - text: Show assets from provider {assetProvider}.
        slots:
          assetProvider: query.assetProvider
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an asset manually
      effect: write
      questions:
      - How do I manually add an asset to the inventory?
      - What fields are required when adding an asset by hand?
      instructions:
      - text: 'Add asset {name} of type {assetType}, classes {assetClassTypes}, owned by {ownerId}: {description}.'
        slots:
          name: requestBody.name
          assetType: requestBody.assetType
          assetClassTypes: requestBody.assetClassTypes
          ownerId: requestBody.ownerId
          description: requestBody.description
      - text: 'Register a virtual asset {name} with external ID {externalId}, type {assetType}, classes {assetClassTypes}, owner {ownerId}: {description}.'
        slots:
          name: requestBody.name
          externalId: requestBody.externalId
          assetType: requestBody.assetType
          assetClassTypes: requestBody.assetClassTypes
          ownerId: requestBody.ownerId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{assetId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an asset
      effect: read
      questions:
      - What do we know about one specific asset?
      - Can I look up a single asset by its ID?
      instructions:
      - text: Get asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Show asset {assetId} with {expand} expanded.
        slots:
          assetId: path.assetId
          expand: query.expand[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{assetId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an asset
      effect: write
      questions:
      - How do I reassign an asset to a new owner?
      - Can I edit an asset's notes or description later?
      instructions:
      - text: Reassign asset {assetId} to owner {ownerId}.
        slots:
          assetId: path.assetId
          ownerId: requestBody.ownerId
      - text: Update the notes on asset {assetId} to {notes}.
        slots:
          assetId: path.assetId
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assets/{assetId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an asset
      effect: destructive
      questions:
      - Can removing a manually-added asset be undone?
      - Which assets am I allowed to delete, virtual or manual ones?
      instructions:
      - text: Remove asset {assetId}.
        slots:
          assetId: path.assetId
      - text: Delete the manually added asset {assetId} from inventory.
        slots:
          assetId: path.assetId
      method: generated
      generated: '2026-09-26'