API Evangelist conversational phrasing for Controlup Devices API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Controlup Devices API
  version: 1.0.0
extends: openapi/controlup-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: 13
- target: $.paths['/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List compliance-managed devices
      effect: read
      questions:
      - Which of my devices have the worst compliance score?
      - Can I find devices whose agent is offline or running an old client version?
      - What devices are in a particular device group or location?
      instructions:
      - text: List all devices managed by ControlUp for Compliance.
      - text: Find devices with score severity {score_severity}.
        slots:
          score_severity: query.score_severity
      - text: List devices in group {device_group} with agent status {agent_status}.
        slots:
          device_group: query.device_group
          agent_status: query.agent_status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{device_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device and its issue summary
      effect: read
      questions:
      - How many issues were detected on one specific device?
      - Can I pull the details of a single device by its ID?
      instructions:
      - text: Show details for device {device_id}.
        slots:
          device_id: path.device_id
      - text: Summarize the issue counts on device {device_id}.
        slots:
          device_id: path.device_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{device_id}/vulnerabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: List CVEs on a device
      effect: read
      questions:
      - Which CVEs were detected on a particular laptop?
      - Is this device exposed to any known vulnerabilities?
      instructions:
      - text: List the vulnerabilities found on device {device_id}.
        slots:
          device_id: path.device_id
      - text: Show the CVEs detected on device {device_id}.
        slots:
          device_id: path.device_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{device_id}/patches'].get
  update:
    x-apievangelist-phrasing:
      intent: List missing patches on a device
      effect: read
      questions:
      - What OS and application patches is this device missing?
      - Can I see only critical missing patches from a specific vendor on one machine?
      instructions:
      - text: List missing patches on device {device_id}.
        slots:
          device_id: path.device_id
      - text: Show missing {severity} patches from {vendor_name} on device {device_id}.
        slots:
          severity: query.severity
          vendor_name: query.vendor_name
          device_id: path.device_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{device_id}/compliance'].get
  update:
    x-apievangelist-phrasing:
      intent: List compliance issues on a device
      effect: read
      questions:
      - Which compliance-category issues does a device have?
      - Are there high-severity compliance findings on this endpoint?
      instructions:
      - text: List compliance issues on device {device_id}.
        slots:
          device_id: path.device_id
      - text: Show {severity} compliance issues for device {device_id}.
        slots:
          severity: query.severity
          device_id: path.device_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{device_id}/misconfig'].get
  update:
    x-apievangelist-phrasing:
      intent: List misconfigurations on a device
      effect: read
      questions:
      - What misconfigurations were detected on a given device?
      - Can I filter a device's misconfiguration issues by remediation status?
      instructions:
      - text: List misconfiguration issues on device {device_id}.
        slots:
          device_id: path.device_id
      - text: Show misconfigurations on device {device_id} with remediation status {remediation_status}.
        slots:
          device_id: path.device_id
          remediation_status: query.remediation_status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete devices
      effect: destructive
      questions:
      - Can I remove several retired devices from compliance monitoring at once?
      - Is there a bulk delete for devices by ID?
      instructions:
      - text: Delete devices {device_ids}.
        slots:
          device_ids: requestBody.device_ids
      - text: 'Remove these devices from ControlUp for Compliance: {device_ids}.'
        slots:
          device_ids: requestBody.device_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List device tags with usage counts
      effect: read
      questions:
      - Which device tags exist, and how many devices use each?
      - What tags have I applied to my devices so far?
      instructions:
      - text: List all device tags.
      - text: Show how many devices carry each device tag.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or remove device tags
      effect: write
      questions:
      - Can I tag a batch of devices in one request?
      - What characters are allowed in a device tag?
      instructions:
      - text: Add tags {tags} to devices {ids}.
        slots:
          tags: requestBody.tags
          ids: requestBody.ids
      - text: Apply tag action {action} with tags {tags} on devices {ids}.
        slots:
          action: requestBody.action
          tags: requestBody.tags
          ids: requestBody.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List device groups with counts
      effect: read
      questions:
      - What device groups exist, and how many devices are in each?
      - Which groups can I assign my devices to?
      instructions:
      - text: List all device groups.
      - text: Show the device count for every device group.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/set-group'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign devices to a group
      effect: write
      questions:
      - Can I move several devices into one device group?
      - Can a device belong to more than one group at a time?
      instructions:
      - text: Put devices {device_ids} into group {group}.
        slots:
          device_ids: requestBody.device_ids
          group: requestBody.group
      - text: Set the device group of {device_ids} to {group}.
        slots:
          device_ids: requestBody.device_ids
          group: requestBody.group
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/{deviceID}/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an action on one device
      effect: write
      questions:
      - Can I trigger a remediation action on just one device?
      - Which endpoint gives more options when acting on a single device?
      instructions:
      - text: Perform an action on device {deviceID}.
        slots:
          deviceID: path.deviceID
      - text: Run a remediation action on the single device {deviceID}.
        slots:
          deviceID: path.deviceID
      method: generated
      generated: '2026-09-26'
- target: $.paths['/devices/action'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an action on many devices
      effect: write
      questions:
      - Can I run the same action on multiple devices at once?
      - Is there a bulk device action endpoint?
      instructions:
      - text: Perform an action across multiple devices.
      - text: Run a bulk action on a set of devices.
      method: generated
      generated: '2026-09-26'