Device Scans

Device scans discover instruments that are available to the host machine but not yet connected. A scan is an asynchronous, long-running background process — typically backed by a device-class–specific subprocess that polls hardware or the local network. Clients start a scan, poll the list of available devices, and either stop the scan once a device has been found or keep it running for continuous discovery.

Endpoints Overview

Scans must be started against a known device class. The same device class is used later when connecting (see Connected Devices). Common values are aesthetix, aesthetix-inline, id-inline and their -mock variants (see Mock Devices).

Starting a Scan

POST /v1/device-scans
Content-Type: application/json

{
  "deviceClass": "aesthetix-inline"
}

curl -X POST http://localhost:42042/v1/device-scans \
  -H "Content-Type: application/json" \
  -d '{ "deviceClass": "aesthetix-inline" }'

Request Body

What happens internally

Starting a scan spawns the device-class–specific subprocess (for Aesthetix-family devices that is Aesthetix.exe / AesthetixKernel.exe). The subprocess handles direct communication with the device, including taking measurements and calculating metrics. It is kept alive for as long as the scan or any device connection of that class is active.

Listing Active Scans

GET /v1/device-scans

Example response:

[
  {
    "identifier": "9d8e2f1a-…",
    "scanFilter": {
      "deviceClass": "aesthetix-inline",
      "serialNumberFilter": null,
      "ipAddressFilter": null
    },
    "status": "running",
    "foundDevices": [
      "12f1d7dd07ac42a088c8f961b39d68ff"
    ]
  }
]

The foundDevices array contains the identifiers of every available device found by this scan so far. To retrieve the full device records, use the available-devices endpoints.

Polling Discovered Devices

While a scan is running, query GET /v1/available-devices to retrieve the discovered devices and their metadata:

GET /v1/available-devices

Example response:

[
  {
    "discovered": "2025-11-12T08:15:26.7825826+00:00",
    "identifier": "12f1d7dd07ac42a088c8f961b39d68ff",
    "deviceClass": "aesthetix-inline",
    "serialNumber": "AXI8000027",
    "serialNumbers": [
      "AXI8000027"
    ],
    "hardwareVersion": "…",
    "firmwareVersion": "…",
    "softwareVersion": "…",
    "componentVersions": []
  }
]

The identifier field is what you pass to POST /v1/devices to establish a connection. See Connected Devices for the follow-up step.

Stopping a Scan

DELETE /v1/device-scans/{scanId}

curl -X DELETE http://localhost:42042/v1/device-scans/9d8e2f1a-…

Stopping a scan tears down the discovery loop. If no connected device of the same class remains, the associated subprocess is shut down as well.

When to Stop the Scan

• USB-attached devices (Aesthetix, ID Inline): stop the scan once the device has been found and you are about to connect. Keeping the scan running adds no value and consumes a subprocess slot.
• Network-discovered devices (Aesthetix Inline): it is acceptable to keep the scan running while working with the device — discovery is low-cost, and clients may want to detect hot-plugged devices on the same network.

Best Practices

• Always start a scan after calling `POST /v1/lifecycle/initialize`. The hub rejects scan requests if the lifecycle services have not been initialized.
• Treat the scan identifier as opaque; do not parse or rely on its format.
• Poll GET /v1/available-devices rather than GET /v1/device-scans/{scanId} to read the discovered devices — available-devices returns full device records, device-scans returns identifiers only.
• Stop scans you no longer need to free the underlying subprocess.
• On shutdown, `POST /v1/lifecycle/shutdown` stops all scans automatically; explicit DELETE is only required when you want to stop a scan mid-session.