Devices

Introduction

Access Token

Access tokens are the secret passwords that gives access to your resources through the APIs. You can create an API token from the Cloud as described in the introduction.
Make sure to keep your tokens secret and to not publish them publicly to prevent any security breach.

API in use

The Cloud API centralizes all your teams, workspaces, devices, applications, logs and telemetries. hub.stereolabs.com/api/v1

List devices

List all the devices present in the workspace identified by workspaceId.

:workspaceId integer

Id of the workspace containing the devices.

fields string

optional List of fields to be returned by the request, by default, or if empty, all the fields are returned.
For example ?fields=id,name,description,connection_status will only return the listed fields of each device.

devices array

List of the devices in the workspace and their details.

/workspaces/:workspaceId/devices

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices

HTTP/1.1 200 OK
{ 
  "devices": [
    {
      "id": "67890",
      "workspace_id": "12345",
      "name": "My first device",
      "description": "",
      "created_at": "1580204174271",
      "connection_status": "ONLINE",
      "connection_log":[...],
      "errors": true,
      "warnings": false,
      "camera": [...],
      "host": {...},
      "applications": [...],
      "parameters": {...}
   },
   ...
  ]
}

Get device information

Get the device information of the device identified by deviceNameOrId that belongs to the workspace identified by workspaceId.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

fields string

id integer

Id of the device.

workspace_id integer

Id of the device's workspace.

name string

Name of the device.

description string

Verbose description of the device.

created_at timestamp

Datetime of the device creation (epoch, milliseconds).

connection_status string

"ONLINE", "OFFLINE" depending on whether the device is currently connected to the cloud or not.

connection_log array

An history of the device connectivity over the last 24 hours. Start and end define the time range, and status is equal to "ONLINE" or "OFFLINE" depending on whether the device is currently connected to the cloud or not.

errors boolean

Whether the device reported an error log which hasn't been marked as read.

warning boolean

Whether the device reported a warning log which hasn't been marked as read.

camera array

Array of objects storing camera information (model, serial number, ...) about each ZED camera connected to the device.

For devices with an edge version lower than 0.64, this field contains a single camera object only.

host object

Contains hardware, software, storage, and network information of the host.

host.hardware object

Details about the host CPU, GPU.

host.storage array

List of the host's mounted drives and their capacity.

host.software object

Current software versions installed on the device.

host.network array

List of the active network interfaces of the host.

applications array

List of applications effectively deployed on the device.

parameters object

Requested and reported values of the editable parameters set for the device.

parameters.reported.core.privacy
parameters.requested.core.privacy object

Requested and reported parameters for the privacy mode, which prevents streaming and recordings when enabled.

enabled: Whether privacy mode should be active or not.

parameters.reported.core.privacy
parameters.requested.core.software object

Requested and reported version of the Edge Agent installed on the device.

edge_agent_versionVersion of the Edge Agent installed on the device.

parameters.reported.core.recording
parameters.requested.core.recording object

Requested and reported parameters of the device recording.

enabled: Whether recordings are currently enabled on the device.
storage_volume: The path to the volume were recording are stored.
retention_rules: The set of rules used to disable recording, or delete previous ones when specific conditions are matched.
retention_rules.condition: "space_full", "remaining_space", or "used_space" to monitor usage of the selected storage volume.
retention_rules.is: target value for "remaining_space" and "used_space" conditions in GB.
retention_rules.action: "delete" to remove latest recordings when the condition is matched, or "disable" to stop recording.

parameters.reported.core.applications
parameters.requested.core.applications object

Requested and reported device parameters about application handling.

storage_volume: The path to the volume were applications are stored.

parameters.reported.core.streams array

Reported device parameters relative to WebRTC streams.

stream_id: The id to identify the stream and request it.
stream_label: A label to differentiate streams on a same device.

parameters.reported.core.secondary_streams array

Reported device parameters relative to MJPEG stream.

name: The name of the MJPEG stream.

/workspaces/:workspaceId/devices/:deviceNameOrId

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId

HTTP/1.1 200 OK
{
  "id": "67890",
  "workspace_id": "12345",
  "name": "My first device",
  "description": "First device created with the REST API",
  "created_at": 1580204174271,
  "connection_status": "ONLINE",
  "connection_log": [
    {
      "status": "OFFLINE",
      "start": 1584439200000,
      "end": 1584442800000
    },
    ...
  ],
  "errors": true,
  "warnings": false,
  "camera": [
    {
    "model": "ZED 2",
    "serial_number": 25990291,
    "camera_firmware_version": "1523",
    "sensor_firmware_version": "774"
  },
],
  "host": {
    "hardware": {
      "cpus": [
        {
          "name": "Cortex-A57",
          "cores": "4",
          "threads": "4",
          "total_memory": 4059
        }
      ],
      "gpus": [
        {
          "arch": "Maxwell",
          "name": "NVIDIA Tegra X1",
          "cores": 128,
          "total_memory": 3964,
          "compute_capability": "5.3"
        }
      ],
      "host": "nano",
      "nvp_model": "MAXN"
    },
    "disks": [ 
      {
        "volume": "/",
        "size": 143.8 // GB
      },
      {
        "volume": "/mnt/SSD",
        "size": 239.32 // GB
      }
    ],
    "software": {
      "os_name": "Ubuntu 18.04.4 LTS",
      "os_release": "L4T R32.2.1", 
      "jetpack": "Jetpack 4.3", 
      "architecture": "aarch64",
      "cuda_version": "10.0.326",
      "kernel_version": "4.9.140-tegra",
      "edge_agent_version": "0.4.1",
      "zed_sdk_version": "3.0.2"
    },
    "network": [ 
      {
        "network_name": "Wired connection 1",
        "ip_address": "192.168.1.67",
        "mac_address": "00:04:4b:e9:eb:ed",
        "name": "eth0",
        "type": "802-3-ethernet"
      }
    ],
  },
  "applications": [
    {
      "id": "101112",
      "deployment_id": 987654,
      "name": "Camera App",
      "release": "0.4.1",
      "deployed_at": "1584439200000",
      "status": "running"
    },
    {
      "id": "161718",
      "deployment_id": 645687,
      "name": "NodeRed",
      "release": "0.4.1",
      "deployed_at": "1584439200000",
      "status": "disabled"
    }
  ],
  "parameters": {
    "reported":{
      "core":{
        "privacy": {
          "enabled": false
        },
        "software": {
          "edge_agent_version": "0.6.0"
        },
        "recording":{
          "storage_volume": "/mnt/SSD",
          "enabled": true,
          "retention_rules": [
            { "condition": "space_full", "action": "delete" }
            { "condition": "remaining_space", "is": 5, "action": "delete" }
            { "condition": "used_space", "is": 45, "action": "disable" }
          ]
        },
        "recording":{
          "status":"running"
        },
        "applications": {
          "storage_volume": "/mnt/SSD",
        },
        "streams": [
          {
            "stream_id": "webrtc_67890_25990291_main_stream_6BHHL",
            "stream_label": "main_stream_25990291",
          },
        ],
        "secondary_streams": [
          {
            "name": "25990291",
          },
        ],
      }
    },
    "requested": {
      "core":{
        "privacy": {
          "enabled": false
        },
        "software": {
          "edge_agent_version": "0.6.0"
        },
        "recording":{
          "storage_volume": "/mnt/SSD",
          "enabled": true,
          "retention_rules": [
            { "condition": "space_full", "action": "delete" }
            { "condition": "remaining_space", is: 5, "action": "delete" }
            { "condition": "used_space", is: 45, "action": "disable" }
          ]
        },
        "applications": {
          "storage_volume": "/mnt/SSD",
        }
      }
    }
  }
}

Create device

Create a device in the workspace identified by the workspaceId.

:workspaceId integer

Id of the workspace containing the devices.

name string

Name of the device to be created.

description string

Verbose description of the device to be created.

id integer

Id of the device.

workspace_id integer

Id of the device's workspace.

name string

Name of the device.

description string

Verbose description provided previously.

created_at timestamp

Creation date of the device (epoch, milliseconds).

connection_status string

Initial connection state of the device OFFLINE.

connection_log array

Initial and empty connection log of the device.

errors boolean

false by default as device didn't reported any errors yet.

warnings boolean

false by default as device didn't reported any warnings yet.

camera object

Information about the ZED camera associated with the device.

host object

Initial and empty information about the device host.

applications array

Initial and empty list of applications reported to be deployed on the device.

parameters object

Initial parameters for the device.

/workspaces/:workspaceId/devices

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices \
  -d '{
  "name": "My new device name",
  "description": "My device description"
}'

HTTP/1.1 200 OK
{ 
  "id": "67890",
  "workspace_id": "12345",
  "name": "My first device",
  "description": "",
  "created_at": "1580204174271",
  "connection_status": "OFFLINE",
  "connection_log": [...],
  "errors": false,
  "warnings": false,
  "camera": [...],
  "host": {...},
  "applications": [...],
  "parameters": {...}
}

Update device name

Update a device name or description.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

name string

optional New name of the device.

description string

optional New verbose description of the device.

name string

The new name of the device.

description string

The new description of the device.

_ _

Other information about the device as detailed in Get Device.

/workspaces/:workspaceId/devices/:deviceNameOrId

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X PUT \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId \
  -d '{
  "name": "My new device name",
  "description": "Updated device description"
}'

HTTP/1.1 200 OK
{ 
  "id": "67890",
  "workspace_id": "12345",
  "name": "My new device name",
  "description": "Updated device description",
  "created_at": "1580204174271",
  "connection_status": "OFFLINE",
  "connection_log":[...],
  "errors": false,
  "warnings": false,
  "camera": [...],
  "host": {...},
  "applications": [...],
  "parameters": {...}
}

Update privacy mode

Enable or disable the privacy mode on the device. The privacy mode prevents any recording or live stream to occur, making sure no video is stored on or streamed by the camera.
You can check the current status of the privacy mode by requesting the device information and inspecting the value of parameters.reported.core.privacy.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

#key string

core.privacy.enabled To enable or disable the privacy mode from the request.

#value json_type

true to enable the privacy mode, false to disable.

/workspaces/:workspaceId/devices/:deviceNameOrId/request

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/request \
  -d '{
  "core.privacy.enabled": true
}'

HTTP/1.1 200 OK
{}

Enable or disable recording

Enable or disable recording on the device.
You can check the current status of the recording by requesting the device information and inspecting the value of parameters.core.reported.recording.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

#key string

core.recording.enabled To perform the request on the recording configuration.

#value json_type

true to enable recording, false to disable.

/workspaces/:workspaceId/devices/:deviceNameOrId/request

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/request \
  -d '{
  "core.privacy.enabled": true
}'

HTTP/1.1 200 OK
{}

Change recording retention rules

Updates all the array of recording retention rules.
You can check the current status of the recording by requesting the device information and inspecting the value of parameters.core.reported.recording.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

#key string

core.recording.retention_rules To perform the request on the recording retention rules.

#value json_type

The new set of rules used to disable recording, or delete previous ones when specific conditions are matched.

condition: "space_full", "remaining_space", or "used_space" to monitor usage of the selected storage volume.
is: target value for "remaining_space" and "used_space" conditions in GB.
action: "delete" to remove latest recordings when the condition is matched, or "disable" to stop recording.

/workspaces/:workspaceId/devices/:deviceNameOrId/request

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/request \
  -d '{
  "core.recording.storage_volume": [
     { "condition": "space_full", "action": "delete" }
     { "condition": "remaining_space", is: 5, "action": "delete" }
  ]
}'

HTTP/1.1 200 OK
{}

Change recording drive

Select the drive to store recordings.
Notice that changing the recording drive will delete previous recordings and start new ones on the selected drive.
You can check the current status of the recording by requesting the device information and inspecting the value of parameters.core.reported.recording.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

#key string

core.recording.storage_volume To perform the request on the recording storage volume.

#value json_type

The path to the drive that should be used for recordings. / for the root drive, or /mnt/myDrive for any mounted drive.

/workspaces/:workspaceId/devices/:deviceNameOrId/request

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/request \
  -d '{
  "core.recording.storage_volume": "/"
}'

HTTP/1.1 200 OK
{}

Change application drive

Select the drive to store the installed applications.
Notice that changing the drive will stop the applications before moving them to the new drive.
You can check the current status of the applications by requesting the device information and inspecting the value of parameters.reported.core.applications.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

#key string

core.applications.storage_volume To perform the request on the applications storage volume.

#value json_type

The path to the drive that should be used for applications. / for the root drive, or /mnt/myDrive for any mounted drive.

/workspaces/:workspaceId/devices/:deviceNameOrId/request

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/request \
  -d '{
  "core.applications.storage_volume": "/"
}'

HTTP/1.1 200 OK
{}

Update the Edge Agent

Set the desired version of the Edge Agent. Device will start the update process in the background.
You can check the current status by requesting the device information and inspecting the value of parameters.reported.core.software.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

#key string

core.software.edge_agent_version To perform the request on the Edge Agent version.

#value json_type

The desired version number like 1.1.0.

/workspaces/:workspaceId/devices/:deviceNameOrId/request

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/request \
  -d '{
  "core.software.edge_agent_version": "1.1.0"
}'

HTTP/1.1 200 OK
{}

Call a function

Sends a function call to the device, which the associated parameters, and return the function result.
Custom functions can be defined in applications to run actions or retrieve information.

:workspaceId integer

Id of the target workspace.

:deviceNameOrId integer

Id or url-encoded name of the target device.

:functionName integer

Name of the remote function to be called on the target device.

parameters object

optional Optional parameters provided to the remote function.

call_id string

Unique identifier of this function call.

name string

Name of the function called function.

result object

Result object returned by the function.

status integer

0 if the function ran normally, any other value if an error occurred during the execution on the device.

/workspaces/:workspaceId/devices/:deviceNameOrId/functions/:functionName

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/functions/:functionName \
  -d '{
  "parameters": {
    "unit": "percent"
  }
}'

HTTP/1.1 200 OK
{
  "call_id": "b8c0032e-a991-4bac-9caf-2ae15842e8e6",
  "name": "getBatteryLevel",
  "result": {
    "level": 98
  },
  "status": 0
}

Reboot device

Sends a reboot request to the device.

:workspaceId integer

Id of the workspace containing the devices.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

/workspaces/:workspaceId/devices/:deviceNameOrId/reboot

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X POST \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/reboot

HTTP/1.1 200 OK
{}

Delete device

Delete the device identified by deviceNameOrId from the workspace identified by workspaceId.

:workspaceId integer

Id of the workspace containing the device.

:deviceNameOrId integer

Id or url-encoded name of the targeted device.

/workspaces/:workspaceId/devices/:deviceNameOrId

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
  -X DELETE \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId

HTTP/1.1 200 OK
{}

Get uptime of device

Get uptime of device between a timestamp and the present.

:start integer

Start timestamp in milliseconds

:uptime float

Uptime percentage of the device within the interval between the timestamp and the present. The returned value is between 0 and 100.

/workspaces/:workspaceId/devices/:deviceNameOrId/uptime/

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/uptime/

HTTP/1.1 200 OK
{
  "uptime": 99.1
}

Get status of network test

Get status of network test identified by testType

:testType string

Type of test to run

:status string

Status of test on device. Can be one of: "success", "error", "not_started", "running"

:download_bitrate integer

Download Bitrate of current test on device in bits per second. Is set to -1 when no value is available.

:upload_bitrate integer

Upload Bitrate of current test on device in bits per second. Is set to -1 when no value is available.

:latency float

Latency of current test on device in seconds. Is set to -1.0 when no value is available

:test_start_timestamp integer

Date at which the test has been started in Unix timestamp.

/workspaces/:workspaceId/devices/:deviceNameOrId/speedTest/:testType

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/speedTest/:testType

HTTP/1.1 200 OK
{
  "status": "running"
  "download_bitrate": 795320000,
  "upload_bitrate": 685116032,
  "latency": -1,
  "test_start_timestamp": 1668698367,
}

Run network test

Trigger the network test specified by :testType on the device.

:testType string

Type of test to run

:status string

Status of test run on device. Can be one of: "success", "error"

/workspaces/:workspaceId/devices/:deviceNameOrId/speedTest/:testType

curl -s \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ${access_token}" \
 https://hub.stereolabs.com/api/v1/workspaces/:workspaceId/devices/:deviceNameOrId/speedTest/:testType

HTTP/1.1 200 OK
{
  "status": "success"
}