# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Drata Devices API
  version: 1.0.0
extends: openapi/drata-devices-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: 7
- target: $.paths['/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List all devices across the company
      effect: read
      questions:
      - Which employee laptops and devices does Drata know about?
      - Can I find a device by its serial number or MAC address?
      - What devices are assigned to a particular person?
      instructions:
      - text: List every device in our account.
      - text: Find the device with serial number {serial}.
        slots:
          serial: query.serialNumber
      - text: Look up the device whose MAC address is {mac}.
        slots:
          mac: query.macAddress
      method: generated
      generated: '2026-09-26'
- target: $.paths['/personnel/{personnelId}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List a person's devices
      effect: read
      questions:
      - What devices belong to one specific employee?
      - Can I check which computers a team member has enrolled?
      instructions:
      - text: List the devices for personnel {personnel}.
        slots:
          personnel: path.personnelId
      - text: Show all machines assigned to employee record {personnel}.
        slots:
          personnel: path.personnelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{deviceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one device
      effect: read
      questions:
      - What compliance details are recorded for one device?
      - Can I look up a single device by its ID?
      instructions:
      - text: Get device {device}.
        slots:
          device: path.deviceId
      - text: Show me the details of device {device}.
        slots:
          device: path.deviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/connections/{connectionId}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List devices reported by a connection
      effect: read
      questions:
      - Which devices came in through a particular connection?
      - Can I see devices synced from one integration only?
      instructions:
      - text: List devices from connection {connection}.
        slots:
          connection: path.connectionId
      - text: Show devices reported by connection {connection} for personnel {personnel}.
        slots:
          connection: path.connectionId
          personnel: query.personnelId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{deviceId}/apps'].get
  update:
    x-apievangelist-phrasing:
      intent: List apps installed on a device
      effect: read
      questions:
      - What applications are installed on an employee's device?
      - Can I get the app inventory for one machine?
      instructions:
      - text: List the apps on device {device}.
        slots:
          device: path.deviceId
      - text: Show the installed software inventory for device {device}.
        slots:
          device: path.deviceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/custom-connections/{connectionId}/devices'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a device via custom connection
      effect: write
      questions:
      - How do I report a device from my own MDM into Drata?
      - Will sending a device with an existing serial number update it instead of duplicating it?
      - Can I record whether disk encryption and firewall are enabled on a device?
      instructions:
      - text: Register a device for personnel {personnel} on custom connection {connection} running {platform} {version}.
        slots:
          personnel: requestBody.personnelId
          connection: path.connectionId
          platform: requestBody.platformName
          version: requestBody.platformVersion
      - text: Upsert device with serial number {serial} for personnel {personnel} on connection {connection}, platform {platform} {version}.
        slots:
          serial: requestBody.serialNumber
          personnel: requestBody.personnelId
          connection: path.connectionId
          platform: requestBody.platformName
          version: requestBody.platformVersion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/custom-connections/{connectionId}/devices/{deviceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a device from a custom connection
      effect: destructive
      questions:
      - Can I remove a device I pushed through a custom connection?
      - What happens to a retired laptop that was reported by my custom integration?
      instructions:
      - text: Delete device {device} from custom connection {connection}.
        slots:
          device: path.deviceId
          connection: path.connectionId
      - text: Remove retired device {device} that custom connection {connection} reported.
        slots:
          device: path.deviceId
          connection: path.connectionId
      method: generated
      generated: '2026-09-26'