# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for WhatsUp Gold Device Group API
  version: 1.0.0
extends: openapi/progress-software-device-group-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 23
- target: $.paths['/api/v1/device-groups/-'].get
  update:
    x-apievangelist-phrasing:
      intent: List device groups
      effect: read
      questions:
      - What device groups are set up in my network monitoring?
      - Can I search device groups by display name and filter by group type?
      - Which device groups can my account access, page by page?
      instructions:
      - text: List all my device groups.
      - text: Find device groups whose name contains {search}.
        slots:
          search: query.search
      - text: List only device groups of type {groupType}, {limit} per page.
        slots:
          groupType: query.groupType
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device group's summary
      effect: read
      questions:
      - How do I look up the summary details of one device group?
      - Can I get a device group's summary in a different view?
      instructions:
      - text: Show me the summary for device group {groupId}.
        slots:
          groupId: path.groupId
      - text: Get device group {groupId} using the {view} view.
        slots:
          groupId: path.groupId
          view: query.view
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a device group
      effect: destructive
      questions:
      - How do I delete a device group I no longer need?
      - Why can't I delete a group that still has child groups or devices in it?
      instructions:
      - text: Delete the empty device group {groupId}.
        slots:
          groupId: path.groupId
      - text: Remove device group {groupId} now that it has no devices or subgroups.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/definition'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a device group's definition
      effect: read
      questions:
      - Where can I see how a device group is defined, including its dynamic or layer 2 rules?
      - What parent group and membership definition does this device group use?
      instructions:
      - text: Show me the definition of device group {groupId}.
        slots:
          groupId: path.groupId
      - text: Get the dynamic and layer 2 definition rules for group {groupId}.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/definition'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a device group's definition
      effect: write
      questions:
      - How do I rename a device group or change its description?
      - Can I move a device group under a different parent group?
      - Is it possible to change the dynamic membership rule of an existing group?
      instructions:
      - text: Rename device group {groupId} to {name}.
        slots:
          groupId: path.groupId
          name: requestBody.name
      - text: Move device group {groupId} under parent group {parentGroupId}.
        slots:
          groupId: path.groupId
          parentGroupId: requestBody.parentGroupId
      - text: Replace the dynamic definition of group {groupId} with {dynamicDefinition}.
        slots:
          groupId: path.groupId
          dynamicDefinition: requestBody.dynamicDefinition
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/child'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a child device group
      effect: write
      questions:
      - How do I create a new subgroup under an existing device group?
      - Can I create a dynamic child group instead of a static one?
      instructions:
      - text: Create a child group named {name} under device group {groupId}.
        slots:
          name: requestBody.name
          groupId: path.groupId
      - text: Add a {groupType} subgroup called {name} beneath parent group {groupId}.
        slots:
          groupType: requestBody.groupType
          name: requestBody.name
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/children'].get
  update:
    x-apievangelist-phrasing:
      intent: List a device group's child groups
      effect: read
      questions:
      - Which subgroups sit underneath a given device group?
      - Can I get the whole nested hierarchy of child groups, not just the first level?
      instructions:
      - text: List the child groups of device group {groupId}.
        slots:
          groupId: path.groupId
      - text: Search the subgroups of {groupId} for names matching {search}.
        slots:
          groupId: path.groupId
          search: query.search
      - text: Show the full child hierarchy under group {groupId}, returnHierarchy {returnHierarchy}.
        slots:
          groupId: path.groupId
          returnHierarchy: query.returnHierarchy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/poll-now'].put
  update:
    x-apievangelist-phrasing:
      intent: Poll every device in a group immediately
      effect: write
      questions:
      - How do I force all devices in a group to be polled right now instead of waiting for the interval?
      - Can I poll only the immediate children of a group rather than every nested device?
      instructions:
      - text: Poll all devices in group {groupId} immediately.
        slots:
          groupId: path.groupId
      - text: Poll now only the devices in group {groupId} matching {search}.
        slots:
          groupId: path.groupId
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/refresh'].put
  update:
    x-apievangelist-phrasing:
      intent: Rediscover all devices in a group
      effect: write
      questions:
      - How do I make discovery rescan every device in a group to pick up hardware changes?
      - Can a group refresh drop discovered data older than a certain number of hours?
      - Is there a way to reset roles, OS and brand on group devices from freshly collected data?
      instructions:
      - text: Refresh discovery for all devices in group {groupId}.
        slots:
          groupId: path.groupId
      - text: Rescan group {groupId} and drop discovered data older than {dropDataOlderThanHours} hours.
        slots:
          groupId: path.groupId
          dropDataOlderThanHours: query.dropDataOlderThanHours
      - text: Refresh devices in group {groupId} with resetOptions {resetOptions}.
        slots:
          groupId: path.groupId
          resetOptions: query.resetOptions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/newDevice'].put
  update:
    x-apievangelist-phrasing:
      intent: Add a single device to monitoring
      effect: write
      questions:
      - How do I start monitoring a new device by its IP address or hostname?
      - Can I add one device and force it to take a specific role?
      instructions:
      - text: Add device {ipOrName} to group {groupId} for monitoring.
        slots:
          ipOrName: query.ipOrName
          groupId: path.groupId
      - text: Add {ipOrName} to group {groupId} using SNMP port {snmpPortToUse}.
        slots:
          ipOrName: query.ipOrName
          groupId: path.groupId
          snmpPortToUse: requestBody.snmpPortToUse
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/newDevice'].patch
  update:
    x-apievangelist-phrasing:
      intent: Bulk add many devices to monitoring
      effect: write
      questions:
      - Can I add a whole list of IP addresses to monitoring in one request?
      - What's the way to onboard dozens of hosts into a device group at once?
      instructions:
      - text: Bulk add these hosts {ipOrNames} to group {groupId}.
        slots:
          ipOrNames: requestBody.ipOrNames
          groupId: path.groupId
      - text: 'Add the devices {ipOrNames} to group {groupId} and expand virtual environments: {expandVirtualEnvironment}.'
        slots:
          ipOrNames: requestBody.ipOrNames
          groupId: path.groupId
          expandVirtualEnvironment: requestBody.expandVirtualEnvironment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the overall status of a device group
      effect: read
      questions:
      - How healthy are the devices in this group overall?
      - Is there a rolled-up up/down status summary for an entire group?
      instructions:
      - text: Show the overall status summary for group {groupId}.
        slots:
          groupId: path.groupId
      - text: Tell me how many devices in group {groupId} are up or down.
        slots:
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List devices in a group
      effect: read
      questions:
      - Which devices belong to a given group, including its nested subgroups?
      - Can I list group devices that are in a particular state, like down?
      instructions:
      - text: List the devices in group {groupId}.
        slots:
          groupId: path.groupId
      - text: Show devices in group {groupId} whose state is {state}.
        slots:
          groupId: path.groupId
          state: query.state
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/devices/-'].get
  update:
    x-apievangelist-phrasing:
      intent: Search devices in a group (dash collection path)
      effect: read
      questions:
      - Can I search a group's device collection by hostname or network address?
      - What does the devices/- collection endpoint of a group return for paging?
      instructions:
      - text: Search the device collection of group {groupId} for {search}.
        slots:
          groupId: path.groupId
          search: query.search
      - text: Page through group {groupId}'s device collection starting at page {pageId}.
        slots:
          groupId: path.groupId
          pageId: query.pageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/devices/-'].post
  update:
    x-apievangelist-phrasing:
      intent: Add existing devices to a group
      effect: write
      questions:
      - How do I put devices I already monitor into another group?
      - Can a device be a member of more than one group?
      instructions:
      - text: Add devices {devices} to group {groupId}.
        slots:
          devices: requestBody.devices
          groupId: path.groupId
      - text: Make the already-monitored devices {devices} members of group {groupId}.
        slots:
          devices: requestBody.devices
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/devices/-'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove several devices from a group
      effect: destructive
      questions:
      - How do I take a batch of devices out of a group in one call?
      - Can I remove multiple devices from a group's membership at once?
      instructions:
      - text: Remove devices {devices} from group {groupId}.
        slots:
          devices: requestBody.devices
          groupId: path.groupId
      - text: Take this set of devices {devices} out of group {groupId}'s membership.
        slots:
          devices: requestBody.devices
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/devices/{deviceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove one device from a group
      effect: destructive
      questions:
      - How do I remove just one device from a group?
      - What happens if I pull a single device out of a group membership?
      instructions:
      - text: Remove device {deviceId} from group {groupId}.
        slots:
          deviceId: path.deviceId
          groupId: path.groupId
      - text: Drop the single device {deviceId} from group {groupId}'s members.
        slots:
          deviceId: path.deviceId
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/devices/-/config/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Export device templates for a group
      effect: read
      questions:
      - Can I export the configuration of every device in a group as templates?
      - Which template options exist, like including layer 2 data or active monitors?
      instructions:
      - text: Export device templates for group {groupId}.
        slots:
          groupId: path.groupId
      - text: Get device templates for group {groupId} with options {options}, including nested groups.
        slots:
          groupId: path.groupId
          options: query.options
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/devices/-/credentials'].get
  update:
    x-apievangelist-phrasing:
      intent: List credentials assigned to a group's devices
      effect: read
      questions:
      - Which credentials are assigned to the devices in a group?
      - Can I narrow the group's credential assignments to one credential type for a group's devices?
      instructions:
      - text: Show the credentials assigned to devices in group {groupId}.
        slots:
          groupId: path.groupId
      - text: List {type} credential assignments for devices in group {groupId}.
        slots:
          type: query.type
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/roles/brand'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign a brand to a group's devices
      effect: write
      questions:
      - How do I set the hardware brand on every device in a group?
      - Can I apply a brand to devices in subgroups too?
      instructions:
      - text: Set the brand of all devices in group {groupId} to {brand}.
        slots:
          groupId: path.groupId
          brand: query.brand
      - text: Assign brand {brand} to group {groupId}, includeHierarchy {includeHierarchy}.
        slots:
          brand: query.brand
          groupId: path.groupId
          includeHierarchy: query.includeHierarchy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/roles/os'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign an operating system to a group's devices
      effect: write
      questions:
      - How do I mark all devices in a group as running a specific operating system?
      - Can the OS assignment cascade to nested groups?
      instructions:
      - text: Set the operating system of devices in group {groupId} to {osName}.
        slots:
          groupId: path.groupId
          osName: query.osName
      - text: Assign OS {osName} to every device under group {groupId}.
        slots:
          osName: query.osName
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/roles/primary'].put
  update:
    x-apievangelist-phrasing:
      intent: Assign a primary role to a group's devices
      effect: write
      questions:
      - How do I change the primary device role, like router or switch, for a whole group?
      - Can I give every device in a group the same primary role?
      instructions:
      - text: Set the primary role of devices in group {groupId} to {primary}.
        slots:
          groupId: path.groupId
          primary: query.primary
      - text: Assign primary role {primary} across group {groupId} and its subgroups.
        slots:
          primary: query.primary
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/device-groups/{groupId}/roles/sub-role'].put
  update:
    x-apievangelist-phrasing:
      intent: Add, remove or clear sub-roles on a group's devices
      effect: write
      questions:
      - Can I add sub-roles to every device in a group at once?
      - How do I clear all sub-roles from the devices in a group?
      instructions:
      - text: Add sub-roles {subroles} to devices in group {groupId}.
        slots:
          subroles: requestBody.subroles
          groupId: path.groupId
      - text: Run sub-role operation {operation} on group {groupId}.
        slots:
          operation: requestBody.operation
          groupId: path.groupId
      method: generated
      generated: '2026-10-01'