Litmus Edge 4.4.x - DeviceHub: Devices

List Devices

POST {{edgeUrl}}/devicehub/v2

List Devices

Returns every configured device in DeviceHub along with the most commonly needed fields. This is the richer projection used by the LE UI's device list and by automation that needs to enumerate devices and their parameters in one call.

For a minimal (ID + Name) projection used by the dashboard tile, see Dashboard > List of Devices.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

query ListDevices {
  ListDevices {
    ID
    Name
    DriverID
    AliasTopics
    CreationTime
    Description
    WorkerParams {
      Name
      Value
      Description
    }
    DHParams {
      Name
      Value
      Description
    }
  }
}

ListDevices accepts an optional input: { IDs: [ID!] } filter (omit to return every device). Any field on Device can be added to the selection, including Properties, MetaData, Topics, StatusPollingRegister, StoppedState, Debug.

Response

200 OK -- application/json

Example response

{
  "data": {
    "ListDevices": [
      {
        "ID": "41FBD12E-C6CD-4539-AD50-336D278B207C",
        "Name": "Rack 2b M258",
        "DriverID": "2AF1FA08-D638-11E9-BB65-2A2AE2DBCCE4",
        "AliasTopics": false,
        "CreationTime": "1970-01-01T00:00:00Z",
        "Description": "",
        "WorkerParams": [
          {
            "Name": "PublishOnPollingInterval",
            "Value": "true",
            "Description": "true"
          }
        ],
        "DHParams": []
      }
    ]
  }
}

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

query ListDevices {
    ListDevices {
        ID
        Name
        DriverID
        AliasTopics
        CreationTime
        Description
        WorkerParams {
            Name
            Value
            Description
        }
        DHParams {
            Name
            Value
            Description
        }
    }
}

Response

Status: 200 OK

{
    "data": {
        "ListDevices": [
            {
                "ID": "41FBD12E-C6CD-4539-AD50-336D278B207C",
                "Name": "Rack 2b M258",
                "DriverID": "2AF1FA08-D638-11E9-BB65-2A2AE2DBCCE4",
                "AliasTopics": false,
                "CreationTime": "1970-01-01T00:00:00Z",
                "Description": "",
                "WorkerParams": [
                    {
                        "Name": "PublishOnPollingInterval",
                        "Value": "true",
                        "Description": "true"
                    }
                ],
                "DHParams": [
                    {
                        "Name": "WatchDogPeriod",
                        "Value": "30",
                        "Description": "30"
                    },
                    {
                        "Name": "WatchDog",
                        "Value": "true",
                        "Description": "true"
                    }
                ]
            }
        ]
    }
}

Create New Device

POST {{edgeUrl}}/devicehub/v2

Create New Device

Creates a single device bound to a driver template. The Properties array supplies the values for every property declared by the driver, and any property the driver marks as Required must be present here. The returned ID is the canonical device UUID used in every subsequent call.

Set StoppedState: true if you want the device to be created but not attempt to connect yet -- useful when you are programmatically populating properties or want to attach registers before the first poll. To start the device later, call Start Device.

Requires: a DriverID from List of Drivers by DriverID and GroupID (ListDriverGroups). The Properties keys come from that driver's GetDriver DeviceProperties. Send the same input to Validate Create Device first: it returns Errors[] (for example DriverID: Unknown DriverID) and creates nothing.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

mutation CreateDevice($input: CreateDeviceRequest!) {
  CreateDevice(input: $input) {
    ID
    Name
    DriverID
    Description
  }
}

Variables (input: CreateDeviceRequest!)

Variables (example)

{
  "input": {
    "DriverID": "5BC98836-CFD4-11E9-BB65-2A2AE2DBCCE4",
    "Name": "apiTestDevice",
    "Description": "deviceCreatedfromAPI",
    "AliasTopics": true,
    "Debug": false,
    "MetaData": [],
    "Properties": [
      { "Key": "name",        "Value": "apiTestDevice" },
      { "Key": "description", "Value": "deviceCreatedfromAPI" }
    ],
    "StatusRegister": null,
    "StoppedState": false
  }
}

Response

200 OK -- application/json

{
  "data": {
    "CreateDevice": {
      "ID": "36B0FDFA-AFC8-4B84-B0B0-296893DB18ED",
      "Name": "apiTestDevice",
      "DriverID": "5BC98836-CFD4-11E9-BB65-2A2AE2DBCCE4",
      "Description": ""
    }
  }
}

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

Common BAD_USER_INPUT causes

• DriverID does not match any installed driver.
• A required property for the driver is missing from Properties.
• A property value fails the driver's type/regex constraints (e.g. a port number outside 0..65535, an enum value not in ListValues).
• Name collides with an existing device.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

mutation CreateDevice($input: CreateDeviceRequest!) {
  CreateDevice(input: $input) {
    ID
    Name
    DriverID
    Description
  }
}

Variables

{
  "input": {
    "AliasTopics": true,
    "Debug": false,
    "MetaData": [],
    "Name": "apiTestDevice",
    "Description": "",
    "Properties": [
      {
        "Key": "name",
        "Value": "apiTestDevice"
      },
      {
        "Key": "description",
        "Value": "deviceCreatedfromAPI"
      }
    ],
    "StatusRegister": null,
    "StoppedState": false,
    "DriverID": "5BC98836-CFD4-11E9-BB65-2A2AE2DBCCE4"
  }
}

Response

Status: 200 OK

{
    "data": {
        "CreateDevice": {
            "ID": "36B0FDFA-AFC8-4B84-B0B0-296893DB18ED",
            "Name": "apiTestDevice",
            "DriverID": "5BC98836-CFD4-11E9-BB65-2A2AE2DBCCE4",
            "Description": ""
        }
    }
}

Update Device

POST {{edgeUrl}}/devicehub/v2

Update Device

Note: UpdateDeviceRequest has no DriverID and no StoppedState. A device cannot be moved to another driver; create a new device instead. Use Start Device / Stop Device to change whether it runs.

Replaces the mutable fields of an existing device. Update Device is a full replacement of the input shape, not a JSON-patch: every value you include is written, every value you omit is left at its server-side default. Provide the full Properties array even when changing a single key, otherwise unspecified keys are reset.

Use this to:

• Re-key the device (Name).
• Re-target a different host (Properties -> networkAddress, networkPort, etc.).
• Toggle Debug or AliasTopics.
• Refresh MetaData such as vendor, model, fw_ver.
• Reassign the StatusRegister used to compute the device's online/offline state.

You cannot change DriverID. To switch drivers, delete the device and create a new one with the desired driver.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

mutation UpdateDevice($input: UpdateDeviceRequest!) {
  UpdateDevice(input: $input) {
    ID
    Name
    DriverID
    Description
    Debug
    Properties              { Name Value Description }
    Topics                  { Direction Encoding Format IntervalMs Topic }
    MetaData                { Name Value Description }
    AliasTopics
    CreationTime
    StatusPollingRegister {
      Name
      ValueType
      Properties { Name Value Description }
    }
  }
}

The selection set in the response is yours to choose; the example above mirrors the LE UI's projection.

Variables (input: UpdateDeviceRequest!)

Variables (example)

{
  "input": {
    "ID": "41FBD12E-C6CD-4539-AD50-336D278B207C",
    "Name": "Rack 2b M258",
    "Description": "Modbus TCP Ethernet Driver",
    "AliasTopics": false,
    "Debug": false,
    "MetaData": [
      { "Key": "device_type",     "Value": "PLC" },
      { "Key": "fw_ver",          "Value": "v2.0.31.40" },
      { "Key": "model",           "Value": "modicon m258" },
      { "Key": "vendor",          "Value": "schneider electric" },
      { "Key": "device_mac_addr", "Value": "00:80:f4:41:20:68" }
    ],
    "Properties": [
      { "Key": "name",                   "Value": "Rack 2b M258" },
      { "Key": "description",            "Value": "Modbus TCP Ethernet Driver" },
      { "Key": "networkAddress",         "Value": "10.17.0.8" },
      { "Key": "networkPort",            "Value": "502" },
      { "Key": "stationId",              "Value": "1" },
      { "Key": "Zero-Based Addressing",  "Value": "1" }
    ],
    "StatusRegister": null
  }
}

Response

200 OK -- application/json. Echoes the new state of the device using the selection set from the request. Server-side defaults are filled in for any optional field you left out.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

Operational note

Updating connection-relevant Properties (host, port, credentials) does not automatically restart the device worker. If the device is already started, the worker is signaled to reconnect; for major topology changes (e.g. switching transport) consider an explicit Stop Device -> update -> Start Device sequence to avoid stale connections.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

mutation UpdateDevice($input: UpdateDeviceRequest!) {
    UpdateDevice(input: $input) {
        ID
        Name
        DriverID
        Description
        Debug
        Properties {
            Name
            Value
            Description
        }
        Topics {
            Direction
            Encoding
            Format
            IntervalMs
            Topic
        }
        MetaData {
            Name
            Value
            Description
        }
        AliasTopics
        CreationTime
        StatusPollingRegister {
            Name
            ValueType
            Properties {
                Name
                Value
                Description
            }
        }
    }
}

Variables

{
    "input": {
        "AliasTopics": false,
        "Debug": false,
        "MetaData": [
            {
                "Key": "device_type",
                "Value": "PLC"
            },
            {
                "Key": "fw_ver",
                "Value": "v2.0.31.40"
            },
            {
                "Key": "model",
                "Value": "modicon m258"
            },
            {
                "Key": "vendor",
                "Value": "schneider electric"
            },
            {
                "Key": "version",
                "Value": "schneider modocon 1.01"
            },
            {
                "Key": "device_mac_addr",
                "Value": "00:80:f4:41:20:68"
            }
        ],
        "Name": "Rack 2b M258",
        "Description": "Modbus TCP Ethernet Driver",
        "Properties": [
            {
                "Key": "name",
                "Value": "Rack 2b M258"
            },
            {
                "Key": "description",
                "Value": "Modbus TCP Ethernet Driver"
            },
            {
                "Key": "networkAddress",
                "Value": "10.17.0.8"
            },
            {
                "Key": "networkPort",
                "Value": "502"
            },
            {
                "Key": "stationId",
                "Value": "1"
            },
            {
                "Key": "Zero-Based Addressing",
                "Value": "1"
            }
        ],
        "StatusRegister": null,
        "ID": "41FBD12E-C6CD-4539-AD50-336D278B207C"
    }
}

Response

Status: 200 OK

{
    "data": {
        "UpdateDevice": {
            "ID": "41FBD12E-C6CD-4539-AD50-336D278B207C",
            "Name": "Rack 2b M258",
            "DriverID": "2AF1FA08-D638-11E9-BB65-2A2AE2DBCCE4",
            "Description": "",
            "Debug": false,
            "Properties": [
                {
                    "Name": "description",
                    "Value": "Modbus TCP Ethernet Driver",
                    "Description": "Modbus TCP Ethernet Driver"
                },
                {
                    "Name": "name",
                    "Value": "Rack 2b M258",
                    "Description": "Rack 2b M258"
                },
                {
                    "Name": "Zero-Based Addressing",
                    "Value": "1",
                    "Description": "1"
                },
                {
                    "Name": "stationId",
                    "Value": "1",
                    "Description": "1"
                },
                {
                    "Name": "networkPort",
                    "Value": "502",
                    "Description": "502"
                },
                {
                    "Name": "networkAddress",
                    "Value": "10.17.0.8",
                    "Description": "10.17.0.8"
                }
            ],
            "Topics": [
                {
                    "Direction": "Output",
                    "Encoding": "JSON",
                    "Format": "Raw",
                    "IntervalMs": null,
                    "Topic": "devicehub.plcstatus.41FBD12E-C6CD-4539-AD50-336D278B207C"
                },
                {
                    "Direction": "Input",
                    "Encoding": "JSON",
                    "Format": "Command",
                    "IntervalMs": null,
                    "Topic": "devicehub.manage.41FBD12E-C6CD-4539-AD50-336D278B207C"
                },
                {
                    "Direction": "Output",
                    "Encoding": "JSON",
                    "Format": "Raw",
                    "IntervalMs": null,
                    "Topic": "devicehub.raw.41FBD12E-C6CD-4539-AD50-336D278B207C.>"
                }
            ],
            "MetaData": [
                {
                    "Name": "device_type",
                    "Value": "PLC",
                    "Description": "PLC"
                },
                {
                    "Name": "device_mac_addr",
                    "Value": "00:80:f4:41:20:68",
                    "Description": "00:80:f4:41:20:68"
                },
                {
                    "Name": "version",
                    "Value": "schneider modocon 1.01",
                    "Description": "schneider modocon 1.01"
                },
                {
                    "Name": "vendor",
                    "Value": "schneider electric",
                    "Description": "schneider electric"
                },
                {
                    "Name": "model",
                    "Value": "modicon m258",
                    "Description": "modicon m258"
                },
                {
                    "Name": "fw_ver",
                    "Value": "v2.0.31.40",
                    "Description": "v2.0.31.40"
                }
            ],
            "AliasTopics": false,
            "CreationTime": "1970-01-01T00:00:00Z",
            "StatusPollingRegister": null
        }
    }
}

Enable/Disable Device Data Storage

PUT {{edgeUrl}}/stats/devices/{{deviceID}}

Enable/Disable Device Data Storage

Requires: an existing device. Its storage entry is created together with the device (default retentionHours: 168, saveAll: false). GET /stats/devices lists it with the device ID in lowercase, while DeviceHub returns it in uppercase, so compare IDs case-insensitively.

Controls whether DeviceHub persists telemetry from this device to the on-device time-series store. This is the same setting exposed by the Data Storage toggle on the device page in the LE UI.

When saveAll is false, no tag values from this device are persisted (the device still publishes to MQTT/integrations in real time). When true, DeviceHub writes to the local store and retains data for retentionHours, rotating older points out.

This endpoint is REST -- the underlying stats service is not part of the DeviceHub GraphQL surface.

Endpoint

PUT {{edgeUrl}}/stats/devices/{{deviceID}}
Content-Type: application/json

{{deviceID}} is the UUID of the target device. Both the path parameter and the body include the ID; they must match.

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Request body

{
  "ID": "{{deviceID}}",
  "name": "boiler-01",
  "retentionHours": 12,
  "saveAll": false
}

Response

200 OK on success, with an empty body or a small JSON ack depending on build. The change applies immediately to the running worker -- no restart required.

Errors

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

{
    "ID": "{{deviceID}}",
    "name": "boiler-01",
    "retentionHours": 12,
    "saveAll": false
}

Response

Status: 204 No Content

Delete Devices graphQL

POST {{edgeUrl}}/devicehub/v2

Delete Devices (GraphQL, bulk)

Deletes one or more devices in a single mutation. The operation is bulk by design -- pass a single-element IDs array to delete one device, or a list to delete many atomically.

Deletes cascade to the device's registers/tags, examples in DeviceHub > Tags, and any topic subscriptions tied to the device. They do not delete time-series data already persisted to the stats store; those points age out via the retention policy configured on the stats service.

For a single-device REST equivalent (path-parameter style), see Delete Device Rest.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

mutation DeleteDevices($input: DeleteDevicesRequest!) {
  DeleteDevices(input: $input)
}

Variables (input: DeleteDevicesRequest!)

Variables (example)

{
  "input": {
    "IDs": [
      "4F2715FE-4B84-4223-AFA6-858504803ED7",
      "8CDACA9A-FF14-482B-B1A0-F85700525980"
    ]
  }
}

Response

200 OK -- application/json. The mutation returns no data on success.

{
  "data": {
    "DeleteDevices": null
  }
}

A null payload indicates the delete succeeded for the IDs that existed; silently-ignored unknown IDs do not surface as errors here. To confirm a specific device was removed, follow up with List Devices or Get Device.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

mutation DeleteDevices ($input : DeleteDevicesRequest!) {
    DeleteDevices(input: $input)
}

Variables

{
    "input": {
        "IDs": [
            "4F2715FE-4B84-4223-AFA6-858504803ED7",
            "8CDACA9A-FF14-482B-B1A0-F85700525980"
        ]
    }
}

Response

Status: 200 OK

{
    "data": {
        "DeleteDevices": null
    }
}

Delete Device Rest

DELETE {{edgeUrl}}/devicehub/devices/{{deviceID}}

Delete Device (REST, single)

Deletes a single device identified by path parameter. This is the REST equivalent of Delete Devices graphQL with a one-element IDs array. The GraphQL form is preferred for new automation -- this REST endpoint exists mainly for legacy clients.

Side effects are identical to the GraphQL form: the device's registers, topic subscriptions, and configuration are removed. Persisted time-series data ages out via the stats retention policy.

Endpoint

DELETE {{edgeUrl}}/devicehub/devices/{{deviceID}}

{{deviceID}} is the UUID of the device to delete.

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Parameters

No request body.

Response

204 No Content on success.

Errors

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Response

Status: 204 No Content

Device Discovery Tool

POST {{edgeUrl}}/devicehub/v2

Device Discovery Tool

Asks a driver to enumerate discoverable endpoints/servers reachable from its configured network neighborhood, without creating a device first. The returned DiscoveryOptions array is a menu of pre-filled property bundles the operator can pick from to spawn a device.

This feature is only available for protocols that support discovery. As of LE 4.0 those are:

• BACnet (the BacnetIP driver)
• OPC UA (the OPC UA Client Advanced driver)

Other drivers return an empty DiscoveryOptions array.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

query Discovery($input: DiscoveryRequest!) {
  Discovery(input: $input) {
    DiscoveryOptions {
      Label
      Description
      Fields {
        Name
        Type
        Value
      }
    }
  }
}

Variables (input: DiscoveryRequest!)

Variables (example, OPC UA)

{
  "input": {
    "DriverID": "2372E68F-BA1B-46E9-BC07-E92CA006B377",
    "Properties": [
      {
        "Key": "Discovery Server URL (Servers and Endpoints Discovery)",
        "Value": "opc.tcp://localhost:4840"
      },
      {
        "Key": "Server URL (Endpoints Discovery)",
        "Value": "opc.tcp://10.17.2.198:53530/OPCUA/SimulationServer"
      }
    ]
  }
}

The exact Keys depend on the driver. List the supported keys via DeviceHub > Drivers > Get Driver and inspect the driver template's discovery-related properties.

Response

200 OK -- application/json

Example response

{
  "data": {
    "Discovery": {
      "DiscoveryOptions": [
        {
          "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
          "Description": "Security Policy: Basic256Sha256, Security Mode: Sign",
          "Fields": [
            { "Name": "SecurityPolicy", "Type": null, "Value": "3" },
            { "Name": "ServerURL", "Type": null, "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer" }
          ]
        }
      ]
    }
  }
}

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

Discovery-specific errors

• BAD_USER_INPUT with DriverID is not discoverable: the driver does not support discovery (only BACnet and OPC UA Advanced do).
• INTERNAL_SERVER_ERROR with a timeout: the discovery scope was too wide or the upstream server did not respond. Narrow the URL or address range.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

query Discovery($input: DiscoveryRequest!) {
  Discovery(input: $input) {
    DiscoveryOptions {
      Label
      Description
      Fields {
        Name
        Type
        Value
      }
    }
  }
}

Variables

{
  "input": {
    "DriverID": "2372E68F-BA1B-46E9-BC07-E92CA006B377",
    "Properties": [
      {
        "Key": "Discovery Server URL (Servers and Endpoints Discovery)",
        "Value": "opc.tcp://localhost:4840"
      },
      {
        "Key": "Server URL (Endpoints Discovery)",
        "Value": "opc.tcp://10.17.2.198:53530/OPCUA/SimulationServer"
      }
    ]
  }
}

Response

Status: 200 OK

{
    "data": {
        "Discovery": {
            "DiscoveryOptions": [
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Basic256Sha256, Security Mode: Sign",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "3"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "1"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Basic128Rsa15, Security Mode: SignAndEncrypt",
                    "Fields": [
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "2"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        },
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "1"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Aes256Sha256RsaPss, Security Mode: SignAndEncrypt",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "5"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "2"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Basic128Rsa15, Security Mode: Sign",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "1"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "1"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Aes256Sha256RsaPss, Security Mode: Sign",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "5"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "1"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Basic256Sha256, Security Mode: SignAndEncrypt",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "3"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "2"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: None, Security Mode: None",
                    "Fields": [
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        },
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "0"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "0"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Aes128Sha256RsaOaep, Security Mode: Sign",
                    "Fields": [
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        },
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "4"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "1"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Basic256, Security Mode: SignAndEncrypt",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "2"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "2"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Basic256, Security Mode: Sign",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "2"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "1"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        }
                    ]
                },
                {
                    "Label": "SimulationServer@DESKTOP-IRI8PIH - opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer",
                    "Description": "Security Policy: Aes128Sha256RsaOaep, Security Mode: SignAndEncrypt",
                    "Fields": [
                        {
                            "Name": "SecurityPolicy",
                            "Type": null,
                            "Value": "4"
                        },
                        {
                            "Name": "SecurityMode",
                            "Type": null,
                            "Value": "2"
                        },
                        {
                            "Name": "ServerURL",
                            "Type": null,
                            "Value": "opc.tcp://DESKTOP-IRI8PIH:53530/OPCUA/SimulationServer"
                        }
                    ]
                }
            ]
        }
    }
}

Device Connection Status

POST {{edgeUrl}}/devicehub/v2

Device Connection Status (subscription)

Streams real-time updates whenever any device's connection state changes (connected, disconnected, reconnecting, error, ...). This is a GraphQL subscription, not a query -- it is designed for clients that hold an open connection and receive a push for every event, not for polling.

The LE UI uses this to live-update the green/red status dots on the device list. Use it from your own dashboards or alerting pipelines for sub-second reactions to device state changes.

Transport

Subscriptions require a long-lived transport. A plain POST to {{edgeUrl}}/devicehub/v2 will return only the first event (or none) and then close. The supported transports are:

The Postman item is shown as a POST for documentation and one-shot testing; switch to a Postman WebSocket request (Files > New > WebSocket Request) when you need the streaming behavior.

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Subscription body

subscription DeviceChanged {
  DeviceChanged {
    DevStatus
    DeviceID
  }
}

DeviceChanged accepts no arguments and fires for every device. To distinguish events, branch on DeviceID client-side.

Available fields

Selectable fields on DeviceChanged include all of:

Event shape

Each event has the same data-wrapped shape as a query response:

{
  "data": {
    "DeviceChanged": {
      "DevStatus": "Connected",
      "DeviceID": "79F3914E-32A1-4227-AC16-023E627EB26E"
    }
  }
}

A burst of Reconnecting followed by Connected is normal after network flaps; treat the most recent event as the source of truth.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

Subscription-specific notes

• If the transport closes unexpectedly, reconnect with backoff. There is no replay or "missed events" buffer -- events that occur while you are disconnected are lost.
• On reconnect, also issue List Devices to reconcile state.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

subscription DeviceChanged {
    DeviceChanged {
        DevStatus
        DeviceID
    }
}

Response

Status: 200 OK

{
    "data": {
        "DeviceChanged": {
            "DevStatus": "Connected",
            "DeviceID": "79F3914E-32A1-4227-AC16-023E627EB26E"
        }
    }
}

Start Device

POST {{edgeUrl}}/devicehub/v2

Start Device

Starts the worker for one or more devices. After StartDevices returns, the device begins polling/connecting and DeviceChanged events will flow for it.

Idempotent for already-running devices -- starting a running device is a no-op and does not return an error.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

mutation StartDevices($input: StartDevicesRequest!) {
  StartDevices(input: $input)
}

Variables (input: StartDevicesRequest!)

Variables (example)

{
  "input": {
    "IDs": ["{{deviceID}}"]
  }
}

Response

200 OK -- application/json. The mutation returns no data on success.

{
  "data": {
    "StartDevices": null
  }
}

A null payload means the start was accepted by DeviceHub. It does not mean the device is connected yet -- subscribe to Device Connection Status or poll List Devices to observe the transition from Starting to Connected.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

mutation StartDevices($input: StartDevicesRequest!) {
    StartDevices(input: $input)
}

Variables

{
    "input": {
        "IDs": [
            "{{deviceID}}"
        ]
    }
}

Response

Status: 200 OK

{
    "data": {
        "StartDevices": null
    }
}

Stop Device

POST {{edgeUrl}}/devicehub/v2

Stop Device

Stops the worker for one or more devices. The device disconnects from its upstream system, stops polling, and stops publishing to integrations. Its configuration remains intact -- use Start Device to resume, or Delete Devices graphQL to remove permanently.

Idempotent for already-stopped devices.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

mutation StopDevices($input: StopDevicesRequest!) {
  StopDevices(input: $input)
}

The Postman item names the operation StopDevicesRequest for legacy reasons; the GraphQL operation name is StopDevices and what matters at the server is the field name in the selection set.

Variables (input: StopDevicesRequest!)

Variables (example)

{
  "input": {
    "IDs": ["{{deviceID}}"]
  }
}

Response

200 OK -- application/json. The mutation returns no data on success.

{
  "data": {
    "StopDevices": null
  }
}

The device transitions through Stopping to Stopped. To observe the transition in real time, subscribe to Device Connection Status.

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

mutation StopDevicesRequest($input: StopDevicesRequest!) {
    StopDevices(input: $input)
}

Variables

{
    "input": {
        "IDs": [
            "{{deviceID}}"
        ]
    }
}

Response

Status: 200 OK

{
    "data": {
        "StopDevices": null
    }
}

Validate Create Device

POST {{edgeUrl}}/devicehub/v2

Validate Create Device

Dry-run validation for a CreateDevice payload. Runs the exact same checks as Create New Device -- driver-specific property rules, name uniqueness, port ranges -- but creates nothing. Use it to pre-flight a device config from a UI form or bulk import before committing.

The request shape is identical to Create New Device (CreateDeviceRequest), so a payload that validates clean here can be sent to CreateDevice unchanged.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

query ValidateCreateDevice($input: CreateDeviceRequest!) {
    ValidateCreateDevice(input: $input) {
        ObjectID
        Errors { FullName TextToDisplay }
        Warnings { FullName TextToDisplay }
    }
}

Arguments

Response

200 OK -- application/json

A null result means the payload is valid -- no errors, no warnings:

{
  "data": {
    "ValidateCreateDevice": null
  }
}

If validation fails, an ObjectValidationResult is returned instead. Each entry pinpoints the offending field:

{
  "data": {
    "ValidateCreateDevice": {
      "ObjectID": null,
      "Errors": [
        {
          "FullName": "Properties.name",
          "TextToDisplay": "Already exist"
        }
      ],
      "Warnings": null
    }
  }
}

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

query ValidateCreateDevice($input: CreateDeviceRequest!) {
    ValidateCreateDevice(input: $input) {
        ObjectID
        Errors { FullName TextToDisplay }
        Warnings { FullName TextToDisplay }
    }
}

Variables

{
    "input": {
        "DriverID": "2AF1FA08-D638-11E9-BB65-2A2AE2DBCCE4",
        "Name": "apiTestDevice",
        "Description": "",
        "Properties": [
            {
                "Key": "networkAddress",
                "Value": "192.168.1.100"
            },
            {
                "Key": "networkPort",
                "Value": "502"
            }
        ],
        "MetaData": [],
        "AliasTopics": false,
        "StoppedState": true,
        "Debug": false,
        "StatusRegister": null
    }
}

Response

Status: 200 OK

{
    "data": {
        "ValidateCreateDevice": null
    }
}

Can Create Device

POST {{edgeUrl}}/devicehub/v2

Can Create Device

Returns true if the license allows creating another DeviceHub device, false once the licensed device limit is reached. Check it before creating devices in bulk so a long import does not fail midway. The register counterpart is Can Create Register.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

query CanCreateDevice { CanCreateDevice }

No arguments.

Response

200 OK -- application/json

{
  "data": {
    "CanCreateDevice": true
  }
}

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

query CanCreateDevice { CanCreateDevice }

Response

Status: 200 OK

{
    "data": {
        "CanCreateDevice": true
    }
}

Can Create Register

POST {{edgeUrl}}/devicehub/v2

Can Create Register

Returns true if the device's register/tag capacity allows creating more registers -- i.e. whether the current license limit has headroom. Check it before bulk-creating tags so a long import does not fail midway.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

query CanCreateRegister { CanCreateRegister }

No arguments.

Response

200 OK -- application/json

Example response

{
  "data": {
    "CanCreateRegister": true
  }
}

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

query CanCreateRegister { CanCreateRegister }

Response

Status: 200 OK

{
    "data": {
        "CanCreateRegister": true
    }
}

Validate Update Device

POST {{edgeUrl}}/devicehub/v2

Validate Update Device

Dry-run validation for an UpdateDevice payload. Runs the same checks as Update Device -- including name-collision detection against other devices -- but changes nothing. Use it to pre-flight edits before committing them.

The request shape is identical to Update Device (UpdateDeviceRequest), so a payload that validates clean here can be sent to UpdateDevice unchanged.

Endpoint

POST {{edgeUrl}}/devicehub/v2
Content-Type: application/json

Authentication

HTTP Basic Auth. Username is your API token, password is empty. The same token is valid across /devicehub/v2, /analytics/v2, /cc, /opcua, and the other LE services.

Request body (GraphQL)

query ValidateUpdateDevice($input: UpdateDeviceRequest!) {
    ValidateUpdateDevice(input: $input) {
        ObjectID
        Errors { FullName TextToDisplay }
        Warnings { FullName TextToDisplay }
    }
}

Arguments

Response

200 OK -- application/json

A null result means the payload is valid -- no errors, no warnings:

{
  "data": {
    "ValidateUpdateDevice": null
  }
}

If validation fails, an ObjectValidationResult is returned instead. Each entry pinpoints the offending field:

{
  "data": {
    "ValidateUpdateDevice": {
      "ObjectID": "7D9B6AE2-9FA8-454A-BC50-1E6C5398BB93",
      "Errors": [
        {
          "FullName": "Properties.name",
          "TextToDisplay": "Already exist"
        }
      ],
      "Warnings": null
    }
  }
}

Errors

GraphQL endpoints return 200 OK even on logical errors. Inspect the errors array in the response body:

{ "errors": [ { "message": "...", "path": ["..."], "extensions": { "code": "..." } } ] }

A non-200 HTTP response means DeviceHub itself is unreachable. See Dashboard > DeviceHub Status.

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Request Body

GraphQL Query

query ValidateUpdateDevice($input: UpdateDeviceRequest!) {
    ValidateUpdateDevice(input: $input) {
        ObjectID
        Errors { FullName TextToDisplay }
        Warnings { FullName TextToDisplay }
    }
}

Variables

{
    "input": {
        "ID": "{{deviceID}}",
        "Name": "apiTestDeviceRenamed",
        "Description": "",
        "Properties": [
            {
                "Key": "networkPort",
                "Value": "503"
            }
        ],
        "MetaData": [],
        "AliasTopics": false,
        "Debug": false,
        "StatusRegister": null
    }
}

Response

Status: 200 OK

{
    "data": {
        "ValidateUpdateDevice": null
    }
}

List Device Data Storage Settings

GET {{edgeUrl}}/stats/devices

List Device Data Storage Settings

Data storage settings for every DeviceHub device: whether its tag values are saved to the time-series database and for how long. Pairs with Enable/Disable Device Data Storage, which changes them for one device.

Endpoint

GET {{edgeUrl}}/stats/devices

Authentication

HTTP Basic Auth. Username is your API token, password is empty. Tokens are managed under System > Access Control > Tokens.

Parameters

None.

Response

200 OK -- application/json. One entry per device.

[
  { "name": "CS1_HMC02", "retentionHours": 24, "saveAll": true, "ID": "b32dd3c7-3ee9-53e0-9881-4793ab61609a" }
]

Errors

TLS note: edge devices use a self-signed certificate by default. Either install the device CA in your client trust store or disable certificate verification when calling this endpoint directly.

Response

Status: 200 OK

[
    {
        "name": "CS1_VMC01",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "a79ebf3c-9360-58f4-a190-3cbf94f57689"
    },
    {
        "name": "CS1_LATHE02",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "c6995533-6bb2-5dbe-85b8-1919569d9f72"
    },
    {
        "name": "CS1_HMC02",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "b32dd3c7-3ee9-53e0-9881-4793ab61609a"
    },
    {
        "name": "CS1_MOULD02",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "bcac471b-319f-5c27-9aab-89760ac4169b"
    },
    {
        "name": "CS1_LATHE01",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "32d87092-bf3c-52c3-9a57-49286dc483d0"
    },
    {
        "name": "CS1_MOULD01",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "5b02049c-7a99-54a7-9c2c-e3a2323e2b52"
    },
    {
        "name": "CS1_HMC01",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "d0913370-6d6d-518a-a4bb-7e529b6a6d47"
    },
    {
        "name": "CS1_MT01",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "ef3cc025-292e-5ae9-8c8f-f51c016c9630"
    },
    {
        "name": "CS1_VMC02",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "f9df967c-5981-5f38-b195-0a1bdf961e6f"
    },
    {
        "name": "CS1_MILL5X01",
        "retentionHours": 24,
        "saveAll": true,
        "ID": "3d004430-1b81-5a7e-b3de-5b0d4ca58548"
    }
]