v1/devices

Use the v1/devices API to create, modify, delete, or get devices. The API also includes options for getting data (channel), management, and metrics data streams.

URI

http://<hostname>/ws/v1/devices

Formats

HTTP method Format Description Parameters
GET /ws/v1/devices Get summary of the device APIs. None
GET /ws/v1/devices/bulk Get a list of all devices in CSV format. group child_groups orderby tag type address name query fields
POST /ws/v1/devices/bulk Create a batch of users. Update
GET /ws/v1/devices/channel/{id} Get a list of data channels for a device. None
GET /ws/v1/devices/channel/{id}/{name} Get a specific data channel for a device. None
GET /ws/v1/devices/inventory List devices. group child_groups size cursor order orderby tag type address name query
GET /ws/v1/devices/inventory/config/{configId} List devices managed by a config. group child_groups size cursor order orderby tag type address name query
POST /ws/v1/devices/inventory Create or modify devices. bundle_device
DELETE /ws/v1/devices/inventory Delete devices. tag, type, address, name
GET, DELETE /ws/v1/devices/inventory/{id} Get or delete a specific device.
PUT /ws/v1/devices/inventory/{id} Update a specific device. update_only allow_swap
GET /ws/v1/devices/management/{id} Get a list of management streams for a device. None
GET /ws/v1/devices/management/{id}/{name} Get a specific management stream for a device. None
GET /ws/v1/devices/metrics/{id} Get a list of health metrics for a device. None
GET /ws/v1/devices/metrics/{id}/{name} Get a specific health metric for a device. None
GET /ws/v1/devices/types Get a list of device types. None

Device fields

address

Device address supplied by the device.

alerts

Total number of fired alerts for the device.

capabilities

Capabilities to enable for the device (write-only):

Capability Description
sm_compression_available Allow compression to be used for SM requests: true or false.
sm_pack_available Allow pack commands to be sent to the device (multiple commands in a single datagram): true or false.
sm_battery_operated Send requests to the device in battery-operated mode: true or false.
sm_udp_enabled Enable SM/UDP for the device: true or false.

channels_uri

Full path to channel data.

carrier/carrier2

The reported network carrier for the primary and 2nd cellular signals.

connection_status

Keyword that indicates the connection status of the device: connected or disconnected.

description

String that describes the device.

extended_address

XBee radio EUI64 extended address for the device.

firmware_version

String that indicates the firmware version of the device.

group

Group path for the device.

id

System-generated identifier for the device.

install_code

Installation code for the device. An installation code is required for any device manufactured with an associated installation code.

  • If you attempt to add a device that requires an installation code with a missing or incorrect code, you receive an HTTP status 400 error code along with a message describing the error.
  • If you are adding multiple devices and one or more of the device installation code is missing or incorrect, you receive an HTTP status 207 error along with a message describing the error.

ip

Local IP address of the device.

last_connect

Date and time the device last connected to Remote Manager in ISO 8601 format.

last_disconnect

Date and time the device last disconnected from Remote Manager in ISO 8601 format.

last_disconnect_reason

Reason the device last disconnected from Remote Manager, if known.

last_update

Date and time the device was last updated in ISO ISO 8601 format.

mac

MAC address of the device.

management_uri

Full path to management data.

metrics_uri

Full path to metrics data.

notes

String that provide notes for the device (formerly user meta data).

parent

System-generated identifier for the parent device.

password

Password for the device (write-only).

provider/provider2

The reported SIM provider for the primary and 2nd cellular SIMs

public_ip

Public IP address of device (formerly called global IP).

restricted_status

Keyword that indicates the restriction status of the device: unrestricted, disabled, restricted, or untrusted.

serial_number

Serial number of the device.

signal_percent

Percent of the primary cellular signal.

signal_percent2

Percent of the 2nd cellular signal.

signal_quality

Signal quality of the primary cellular signal.

signal_quality2

Signal quality of the 2nd cellular signal.

signal_strength

Signal strenth of the primary cellular signal.

signal_strenth2

Signal strength of the 2nd cellular signal.

tags

An array of tags associated with the device.

type

String that indicates the device type for the device.

vendor_id

Vendor identifier assigned to the device.

Channel, management, and metric fields

id

System-generated identifier for the device.

name

Name for the data channel.

value

Current value of the channel.

units

Units for the channel value.

timestamp

Time the current value was reported (ISO 8601 standard format).

history_uri

URI to the history of channel values (in streams).

customer_id

Identifier for the customer that owns the data.

Parameters

Name Type Description Notes
tag string Query devices with matching tags. (tag | type | address) Use only one per request.
type string Query devices by type.
address string Query devices by address.
cursor string Cursor to get the next page of devices. Omit on initial call.
fields string Comma-separated list of fields to return for bulk API
size integer Number of itmes to return. The maximum and default is 1000.

© 2023 Digi International Inc. All rights reserved.

List All Devices

The following example shows how to list all devices in your inventory.

Request

GET /ws/v1/devices/inventory

Response

{
  "count" : 2,
  "size" : 1000,
  "start" : 0,
  "total" : 2,
  "list" : [ 
  {
    "channels_uri": "/ws/v1/devices/channels/00000000-00000000-0040FFFF-FF8001B0",
    "metrics_uri": "/ws/v1/devices/metrics/00000000-00000000-0040FFFF-FF8001B0",
    "capabilities": {
        "sm_compression_available": true,
        "sm_pack_available": true,
        "sms_enabled": true,
        "cli_service_available": true,
        "sm_encryption_key_distribution_service_available": true,
        "speedtest_available": true,
        "modem_firmware_update_available": true
    },
    "geoposition": {
        "type": "Point",
        "coordinates": [
            -92.505,
            44.066
        ]
    },
    "customer_id": 42,
    "type": "Digi TX64",
    "name": "DeadPool",
    "vendor_id": 4261412874,
    "public_ip": "199.1.2.3",
    "ip": "192.1.2.3",
    "connection_status": "connected",
    "id": "00000000-00000000-0040FFFF-FF8001B0",
    "restricted_status": "unrestricted",
    "serial_number": "WR64-000049",
    "contact": "Ryan Reynolds",
    "description": "Home Router",
    "location": "Rochester, MN",
    "sku": "WR64-A121",
    "firmware_version": "22.5.50.46",
    "firmware_status": "low",
    "last_connect": "2022-07-12T05:20:30.843Z",
    "last_disconnect": "2022-07-12T05:07:14.020Z",
    "last_update": "2022-07-12T14:32:31.167Z",
    "health_status": "normal",
    "carrier": "Verizon",
    "signal_strength": -94,
    "signal_percent": 32,
    "network": "4g",
    "maintenance_mode": "off",
    "compliant": "yes",
    "last_compliant": "2022-05-25T09:49:59.730Z",
    "last_noncompliant": "2022-04-13T04:00:08.793Z",
    "last_noncompliant_reason": "1 settings are not compliant: system/1/banner",
    "connection_type": "Ethernet",
    "cellular_modem_version": "24.01.526",
    "in_maintenance_window": "no",
    "mac": "02:00:00:00:04:00",
    "alerts": 1,
    "registration_date": "2022-03-17T18:09:00.000Z",
    "group": "Stores",
    "management_uri": "/ws/v1/devices/management/00000000-00000000-0040FFFF-FF8001B0"
  },
  {
    "id" : "F9F967B4-33804DCE-2BDC4702-45053B1C",
    "vendor_id" : 4261412871,
    "type" : "DIA Device",
    "restricted_status" : "untrusted",
    "connection_status" : "disconnected",
    "description" : "Thermostat",
    "tags" : ["tstat"],
    "group" : "Primary",
    "address" : "dia/00000000-00000000-00409DFF-FF298D0E/sensor0",
    "parent" : "00000000-00000000-00409DFF-FF298D0E"
  }
 ]
}

© 2023 Digi International Inc. All rights reserved.

List Devices Using Query by Tag

The following example shows how to list all devices that are tagged with a specific tag.

Request

GET /ws/v1/devices/inventory?query=tags='myTag'

Response

{
  "count" : 3,
  "size" : 1000,
  "list" : [ 
  {
    "channels_uri" : "/ws/v1/devices/channels/8C1C080F-A8214448-2674ED16-B9196C0E",
    "metrics_uri" : "/ws/v1/devices/metrics/8C1C080F-A8214448-2674ED16-B9196C0E",
    "group" : "",
    "management_uri" : "/ws/v1/devices/management/8C1C080F-A8214448-2674ED16-B9196C0E",
    "type" : " ",
    "connection_status" : "disconnected",
    "id" : "8C1C080F-A8214448-2674ED16-B9196C0E",
    "restricted_status" : "unrestricted",
    "tags" : [ "myTag" ],
    "health_status" : "unknown",
    "maintenance_mode" : "off"
  }, 
  {
    "channels_uri" : "/ws/v1/devices/channels/BD2EA7BE-60DF46A6-EBBF5052-5B9217FC",
    "metrics_uri" : "/ws/v1/devices/metrics/BD2EA7BE-60DF46A6-EBBF5052-5B9217FC",
    "group" : "",
    "management_uri" : "/ws/v1/devices/management/BD2EA7BE-60DF46A6-EBBF5052-5B9217FC",
    "type" : " ",
    "connection_status" : "disconnected",
    "id" : "BD2EA7BE-60DF46A6-EBBF5052-5B9217FC",
    "restricted_status" : "unrestricted",
    "tags" : [ "myTag" ],
    "health_status" : "unknown",
    "maintenance_mode" : "off"
  }, 
  {
    "channels_uri" : "/ws/v1/devices/channels/BF652035-B3BA464A-B5C95C90-770A4838",
    "metrics_uri" : "/ws/v1/devices/metrics/BF652035-B3BA464A-B5C95C90-770A4838",
    "group" : "",
    "management_uri" : "/ws/v1/devices/management/BF652035-B3BA464A-B5C95C90-770A4838",
    "type" : " ",
    "connection_status" : "disconnected",
    "id" : "BF652035-B3BA464A-B5C95C90-770A4838",
    "restricted_status" : "unrestricted",
    "notes" : "yo",
    "tags" : [ "myTag" ],
    "health_status" : "unknown",
    "maintenance_mode" : "off"
  } ]
}

© 2023 Digi International Inc. All rights reserved.

Get Single Device

The following example shows how to get details for a single device with an ID of 00000000-00000000-0040FFFF-FF8001B0.

Request

GET /ws/v1/devices/inventory/00000000-00000000-0040FFFF-FF8001B0

Response

{
    "alerts": 1,
    "capabilities": {
        "cli_service_available": true,
        "modem_firmware_update_available": true,
        "sm_compression_available": true,
        "sm_encryption_key_distribution_service_available": true,
        "sm_pack_available": true,
        "sms_enabled": true,
        "speedtest_available": true
    },
    "carrier": "Verizon",
    "cellular_modem_version": "24.01.526",
    "channels_uri": "/ws/v1/devices/channels/00000000-00000000-0040FFFF-FF8001B0",
    "compliant": "yes",
    "connection_status": "disconnected",
    "connection_type": "Ethernet",
    "contact": "Ryan Reynolds",
    "customer_id": 57639,
    "description": "Home Router",
    "firmware_status": "up_to_date",
    "firmware_version": "22.5.50.62",
    "geoposition": {
        "coordinates": [
            -90,
            45
        ],
        "type": "Point"
    },
    "group": "ExampleGroup",
    "health_status": "normal",
    "id": "00000000-00000000-0040FFFF-FF8001B0",
    "in_maintenance_window": "no",
    "ip": "192.168.1.183",
    "last_compliant": "2022-05-25T09:49:59.730Z",
    "last_connect": "2022-07-14T03:14:59.497Z",
    "last_disconnect": "2022-07-14T14:28:59.100Z",
    "last_noncompliant": "2022-04-13T04:00:08.793Z",
    "last_noncompliant_reason": "1 settings are not compliant: system/1/banner",
    "last_update": "2022-07-14T14:26:53.187Z",
    "location": "Rochester, MN",
    "mac": "02:00:00:00:04:00",
    "maintenance_mode": "off",
    "management_uri": "/ws/v1/devices/management/00000000-00000000-0040FFFF-FF8001B0",
    "metrics_uri": "/ws/v1/devices/metrics/00000000-00000000-0040FFFF-FF8001B0",
    "name": "DeadPool",
    "network": "4g",
    "public_ip": "9.9.9.9",
    "registration_date": "2022-03-17T18:09:00.000Z",
    "restricted_status": "unrestricted",
    "serial_number": "WR64-000049",
    "signal_percent": 32,
    "signal_strength": -94,
    "sku": "WR64-A121",
    "type": "Digi TX64",
    "vendor_id": 4261412874
}

© 2023 Digi International Inc. All rights reserved.

Create Single Device

Use the following API to create or update one or more devices. Almost all devices require specifying an install_code field. The install code field is the secure password printed on the device label. If you don’t have the install code, the device cannot be registered to your account.

The initial step of adding the device to your account is commonly called “provisioning” or “to provision” a device.

The request payload can include a single device or multiple devices. Multiple devices must be wrapped in an array for JSON. The response always returns the devices as a list.

The following sample JSON request creates a device with various settings. Most of the settings available in the Get Single Device page can be specified.

Request

POST /ws/v1/devices/inventory?bundle_device=true

Payload:

{
  "id": "00000000-00000000-0040FFFF-FF8001B0",
  "install_code": "device-default-password-from-label",
  "name": "Deadpool",
  "tags" : ["Marvel","AntiHero"],
  "group": "ExampleGroup",
}

Response

{
    "count": 1,
    "list": [
        {
            "channels_uri": "/ws/v1/devices/channels/00000000-00000000-0040FFFF-FF8001B0",
            "connection_status": "disconnected",
            "customer_id": 57639,
            "firmware_status": "not_identified",
            "group": "ExampleGroup",
            "health_status": "unknown",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "in_maintenance_window": "yes",
            "mac": "00:40:FF:80:01:B1",
            "maintenance_mode": "off",
            "management_uri": "/ws/v1/devices/management/00000000-00000000-0040FFFF-FF8001B0",
            "metrics_uri": "/ws/v1/devices/metrics/00000000-00000000-0040FFFF-FF8001B0",
            "name": "Deadpool",
            "restricted_status": "unrestricted",
            "tags": [
                "Marvel",
                "AntiHero"
            ],
            "type": " "
        }
    ]
}

About the bundle_device parameter

bundle_device=true causes the API to register a device as a Digi 360 device (also known as Lifecycle Assurance). The device is provisioned into your Remote Manager account and registered in Digi’s ERP systems. You should use this option unless you have good reason not to. One direct benefit is that the your Remote Manager device limit will never prevent you from provisioning this device if it is a 360/LCA device. Adding devices through the Remote Manager web interface uses this same behavior.

Specifying your reseller

You can optionally add a reseller field in the HTTP body payload. The value of that field must be numerical. This will help Digi bill renewals through your reseller. You can find your reseller’s numerical ID by using the following API:

GET /ws/v1/billing/partners

© 2023 Digi International Inc. All rights reserved.

Create Multiple Devices

The following sample JSON request creates two devices with various settings. Most of the settings available in the Get Single Device page can be specified.

Request

POST /ws/v1/devices/inventory

Payload

[
  {
    "id": "00000000-00000000-0040FFFF-FF8001B1",
    "install_code": "device-default-password-from-label",
    "name": "Deadpool2",
    "tags" : ["Marvel","AntiHero"],
    "group": "ExampleGroup"
  },
 {
    "id": "00000000-00000000-0040FFFF-FF8001B2",
    "install_code": "device-default-password-from-label",
    "name": "Superman",
    "tags" : ["DC","Hero"],
    "group": "ExampleGroup"
  }
]

Response

{
    "count": 2,
    "list": [
        {
            "alerts": 0,
            "carrier": "AT&T",
            "channels_uri": "/ws/v1/devices/channels/00000000-00000000-0040FFFF-FF8001B1",
            "connection_status": "disconnected",
            "customer_id": 7493,
            "firmware_status": "not_identified",
            "firmware_version": "22.5.0.0",
            "group": "ExampleGroup",
            "health_status": "unknown",
            "id": "00000000-00000000-0040FFFF-FF8001B1",
            "in_maintenance_window": "yes",
            "last_update": "2022-07-19T19:05:10.870Z",
            "mac": "00:40:FF:80:01:B1",
            "maintenance_mode": "off",
            "management_uri": "/ws/v1/devices/management/00000000-00000000-0040FFFF-FF8001B1",
            "metrics_uri": "/ws/v1/devices/metrics/00000000-00000000-0040FFFF-FF8001B1",
            "name": "Deadpool2",
            "registration_date": "2022-06-16T21:03:00.000Z",
            "restricted_status": "unrestricted",
            "tags": [
                "Marvel",
                "AntiHero"
            ],
            "type": "Digi TX64"
        },
        {
            "channels_uri": "/ws/v1/devices/channels/00000000-00000000-0040FFFF-FF8001B2",
            "connection_status": "disconnected",
            "customer_id": 7493,
            "firmware_status": "not_identified",
            "group": "ExampleGroup",
            "health_status": "unknown",
            "id": "00000000-00000000-0040FFFF-FF8001B2",
            "in_maintenance_window": "yes",
            "mac": "00:40:FF:80:01:B2",
            "maintenance_mode": "off",
            "management_uri": "/ws/v1/devices/management/00000000-00000000-0040FFFF-FF8001B2",
            "metrics_uri": "/ws/v1/devices/metrics/00000000-00000000-0040FFFF-FF8001B2",
            "name": "Superman",
            "restricted_status": "unrestricted",
            "tags": [
                "DC",
                "Hero"
            ],
            "type": " "
        }
    ]
}

© 2023 Digi International Inc. All rights reserved.

Edit Device

The following examples shows how to edit various fields including the tags list, group, contact name and geoposition of a device.

Request

PUT ws/v1/devices/inventory/00000000-00000000-0040FFFF-FF8001B1

Payload

{
  "tags" : ["bad"],
  "group": "NewGroup",
  "contact": "Ryan Reynolds",
  "location": "Rochester, MN",
  "description": "Home Router",
  "geoposition": {
     "coordinates": [
        -90,
         45
     ],
     "type": "Point"
  }
}

Response

{
    "alerts": 0,
    "carrier": "AT&T",
    "channels_uri": "/ws/v1/devices/channels/00000000-00000000-0040FFFF-FF8001B1",
    "connection_status": "disconnected",
    "contact": "Ryan Reynolds",
    "customer_id": 7493,
    "description": "Home Router",
    "firmware_status": "not_identified",
    "firmware_version": "22.5.0.0",
    "geoposition": {
        "coordinates": [
            -90.0,
            45.0
        ],
        "type": "Point"
    },
    "group": "NewGroup",
    "health_status": "unknown",
    "id": "00000000-00000000-0040FFFF-FF8001B1",
    "in_maintenance_window": "yes",
    "last_update": "2022-07-19T19:05:10.870Z",
    "location": "Rochester, MN",
    "mac": "00:40:FF:80:01:B1",
    "maintenance_mode": "off",
    "management_uri": "/ws/v1/devices/management/00000000-00000000-0040FFFF-FF8001B1",
    "metrics_uri": "/ws/v1/devices/metrics/00000000-00000000-0040FFFF-FF8001B1",
    "name": "Deadpool",
    "registration_date": "2022-06-16T21:03:00.000Z",
    "restricted_status": "unrestricted",
    "tags": [
        "bad"
    ],
    "type": "Digi TX64"
}

© 2023 Digi International Inc. All rights reserved.

List device metric streams

The following examples shows how to list the metric streams being reported by a device. A device can have many metric streams, or data channels.

Request

GET ws/v1/devices/metrics/00000000-00000000-0040FFFF-FF8001B0

Response

{
    "count": 98,
    "list": [
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/uptime",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/uptime",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "seconds",
            "value": "3600"
        },
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/cpu/used",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/cpu/used",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "%",
            "value": "9.350000"
        },
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/storage/var/used",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/storage/var/used",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "%",
            "value": "3.000000"
        },
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/storage/tmp/used",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/storage/tmp/used",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "%",
            "value": "0.000000"
        },
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/storage/opt/used",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/storage/opt/used",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "%",
            "value": "4.000000"
        },
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/reboots",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/reboots",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "occurrences",
            "value": "0"
        },
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/mem/used",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/mem/used",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "%",
            "value": "5.980000"
        },
        {
            "customer_id": 57639,
            "history_uri": "/ws/v1/streams/history/00000000-00000000-0040FFFF-FF8001B0/metrics/sys/location",
            "id": "00000000-00000000-0040FFFF-FF8001B0",
            "name": "metrics/sys/location",
            "timestamp": "2022-07-18T22:45:00.000Z",
            "units": "json",
            "value": "{\"type\":\"Feature\",\"geometry\":{\"type\":\"Point\",\"coordinates\": [0.000000, 0.000000, 0.0] }}"
        },
        ...etc...
    ]
}

© 2023 Digi International Inc. All rights reserved.

Delete a Device

The following example shows how to delete a device from your inventory.

DELETE /ws/v1/devices/inventory/00000000-00000000-0040FFFF-FF8001B0

No response is returned unless there is an error.

The “Deleted-Count” header is set to “1” in the HTTP response indicating a successful deletion.