API Evangelist conversational phrasing for Hubble Platform 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 Hubble Platform Devices API
  version: 1.0.0
extends: openapi/hubble-network-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['/v2/org/{org_id}/devices'].post
  update:
    x-apievangelist-phrasing:
      intent: Register new devices in bulk
      effect: write
      questions:
      - How do I register a batch of new devices with the right encryption key length?
      - Can I give names and tags to devices at the moment I register them?
      - Is it possible to get the new device keys back as hex instead of Base64?
      instructions:
      - text: Register {n_devices} new devices in org {org_id} using {encryption} encryption.
        slots:
          n_devices: requestBody.n_devices
          org_id: path.org_id
          encryption: requestBody.encryption
      - text: Register devices named {names} in org {org_id} with {encryption} encryption and tags {tags}.
        slots:
          names: requestBody.names
          org_id: path.org_id
          encryption: requestBody.encryption
          tags: requestBody.tags
      - text: Provision devices in org {org_id} with {encryption} encryption and return their keys in {key_format} format.
        slots:
          org_id: path.org_id
          encryption: requestBody.encryption
          key_format: query.key_format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/org/{org_id}/devices'].get
  update:
    x-apievangelist-phrasing:
      intent: List registered devices
      effect: read
      questions:
      - What devices are registered to my organization?
      - Can I list only devices that sent a packet within a certain time window?
      - Which of my devices are tagged for the sandbox environment?
      instructions:
      - text: List all registered devices in organization {org_id}.
        slots:
          org_id: path.org_id
      - text: List devices in org {org_id} whose last packet falls in {filter_most_recent_packet_ts}.
        slots:
          org_id: path.org_id
          filter_most_recent_packet_ts: query.filter_most_recent_packet_ts
      - text: List devices in org {org_id} with platform tag {filter_tags}, sorted by {sort_field}.
        slots:
          org_id: path.org_id
          filter_tags: query.filter_tags
          sort_field: query.sort_field
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/org/{org_id}/devices'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete many devices at once
      effect: destructive
      questions:
      - How do I remove hundreds of devices from my organization in a single request?
      - What's the maximum number of devices I can delete in one go?
      instructions:
      - text: Delete devices {device_ids} from organization {org_id} in one batch.
        slots:
          device_ids: requestBody.device_ids
          org_id: path.org_id
      - text: Bulk remove this list of up to 1000 devices, {device_ids}, from org {org_id}.
        slots:
          device_ids: requestBody.device_ids
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/org/{org_id}/devices'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update many devices in one request
      effect: write
      questions:
      - Can I rename or retag a large group of devices with a single call?
      - Is it safe to retry a bulk device update if it fails partway through?
      instructions:
      - text: Apply these bulk device updates {updates} in organization {org_id}.
        slots:
          updates: requestBody.updates
          org_id: path.org_id
      - text: Batch update up to 1000 devices in org {org_id} with changes {updates}.
        slots:
          org_id: path.org_id
          updates: requestBody.updates
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/org/{org_id}/devices/{device_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a single device
      effect: read
      questions:
      - How do I pull up the details for one specific registered device?
      - What does Hubble Network have on record for a particular device ID?
      instructions:
      - text: Get device {device_id} in organization {org_id}.
        slots:
          device_id: path.device_id
          org_id: path.org_id
      - text: Show me the registration details for device {device_id} in org {org_id}.
        slots:
          device_id: path.device_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/org/{org_id}/devices/{device_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one registered device
      effect: destructive
      questions:
      - How do I deregister a single device I've retired?
      - Can I remove just one device from my organization without a batch request?
      instructions:
      - text: Delete device {device_id} from organization {org_id}.
        slots:
          device_id: path.device_id
          org_id: path.org_id
      - text: Deregister the single retired device {device_id} in org {org_id}.
        slots:
          device_id: path.device_id
          org_id: path.org_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/org/{org_id}/devices/{device_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename, retag or relocate one device
      effect: write
      questions:
      - How do I set a fixed install location on one of my devices?
      - Can I move a single device from my sandbox org to its paired production org?
      - How many tags can one device carry?
      instructions:
      - text: Rename device {device_id} in org {org_id} to {set_name}.
        slots:
          device_id: path.device_id
          org_id: path.org_id
          set_name: requestBody.set_name
      - text: Set the install location of device {device_id} in org {org_id} to {set_install_location}.
        slots:
          device_id: path.device_id
          org_id: path.org_id
          set_install_location: requestBody.set_install_location
      - text: Move device {device_id} from org {org_id} to paired org {set_destination_org_id}.
        slots:
          device_id: path.device_id
          org_id: path.org_id
          set_destination_org_id: requestBody.set_destination_org_id
      method: generated
      generated: '2026-09-26'