This section lists the APIs for performing operations on devices, device templates, device authentication, device commands, and files.

Enroll Device

Header 
Authorization : {{DeviceAccessToken}}
Required Permissions

You must have the Enroll Device permission to perform this operation.

API
/api/devices/{id}/enroll
Method
GET
Required Parameters
Name Description
id

string

Device identifier.
Response 
{
  "id": "string"
}

Get a Device

Required Permissions

You must have the View Device permission to perform this operation.

API
/api/devices/{id}
Method
GET
Required Parameters
Name Description
id

string

Device identifier.
Response 
{  
   "id":"8d33b386-154e-46fd-9d19-b1452fb9da30",
   "name":"Gateway3",
   "deviceType":"GATEWAY",
   "templateId":"492debf2-735e-4ddf-9440-d5542adf1770",
   "systemProperties":[  
      {  
         "name":"os-sysname",
         "value":"Linux"
      }
   ],
   "customProperties":[  
      {  
         "name":"a",
         "value":"a"
      }
   ],
   "enrollmentState":"ENROLLED",
   "parentGatewayId":"8d33b386-154e-46fd-9d19-b1452fb9da30",
   "orgId":"1a813d5d-da81-410b-b252-b8ec9a91e069",
   "createdTime":1564983544640,
   "lastUpdatedTime":1565071895936,
   "updateVersion":15
}

List All Devices

Required Permissions

You must have the View Device permission to perform this operation.

API
/api/devices
Method
GET
Optional Parameters
Name Description
parentId

string

Parent device ID.
name

string

Device name.
deviceType

string

Device type:
  • GATEWAY
  • THING
id

string

Device ID.
enrollmentState

string

Device states:
  • REGISTERED
  • ENROLLED
  • UNENROLLED
  • DELETED
templateId

string

Template ID.
page.number

int32

Page number.
page.size

string

Page size.
Response 
{
  "pageInfo": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  },
  "devices": [
    {
      "name": "string",
      "systemProperties": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "templateId": "string",
      "updateVersion": "string",
      "createdTime": "string",
      "deviceType": "GATEWAY",
      "customProperties": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "parentId": "string",
      "enrollmentState": "ENROLLED",
      "orgId": "string",
      "id": "string",
      "lastUpdatedTime": "string"
    }
  ]
}

Register a Device

Required Permissions

You must have the Create Device permission to perform this operation.

API
/api/devices
Method
POST
Parameters
Name Description
parentId

string

Parent ID for the relationship. (This is an optional parameter.)
name

string

Device name.
templateName

string

Device template name.
Input Example 
{
  "parentId": "string",
  "name": "string",
  "templateName": "string"
}
Response 
{
  "id": "string"
}

Unenroll a Device

Required Permissions

You must have the Unenroll Device permission to perform this operation.

API
/api/devices/{id}/unenroll
Method
DELETE
Required Parameters
Name Description
id

string

Device identifier.
Response 
{}

Delete a Device

Required Permissions

You must have the Delete Device permission to perform this operation.

API
/api/devices/{id}
Method
DELETE
Required Parameters
Name Description
id

string

Device identifier.
Response 
{}

Get a List of Connected Devices

Required Permissions

You must have the View Device permission to perform this operation.

API
/api/devices/{{device_id}}/connected-devices
Method
GET
Parameters
Name Description
type

string

The supported values are ALL and THINGS.
page.number

int32

The number of pages to display.
page.size

string

The number of entries per page.
Response 
{
  "devices": [
    {
      "name": "CD_01_02",
      "deviceType": "THING",
      "templateId": "21d30e3d-3176-4445-b2cd-e65ce662d76f",
      "enrollmentState": "REGISTERED",
      "parentId": "12c6006e-a27f-47eb-8a42-1313f3edd57f",
      "parentGatewayId": "413d5b55-ec4a-4026-a89a-7eb3986f8f4e",
      "orgId": "618ab173-efa4-4d8a-8793-fa5377f5bd7e",
      "createdTime": 1570106199609,
      "lastUpdatedTime": 1570106199609,
      "updateVersion": 1,
      "id": "30590692-ec76-4935-b09a-3b8fafeda4ef"
    },
    {
      "name": "CD_01_01",
      "templateName": "Thing_02",
      "deviceType": "THING",
      "templateId": "21d30e3d-3176-4445-b2cd-e65ce662d76f",
      "enrollmentState": "REGISTERED",
      "parentId": "12c6006e-a27f-47eb-8a42-1313f3edd57f",
      "parentGatewayId": "413d5b55-ec4a-4026-a89a-7eb3986f8f4e",
      "orgId": "618ab173-efa4-4d8a-8793-fa5377f5bd7e",
      "createdTime": 1570106188372,
      "lastUpdatedTime": 1570106188372,
      "updateVersion": 1,
      "id": "b522ccdc-6158-48d4-84db-76302b6c066f"
    },
    {
      "name": "CD_01",
      "templateName": "Thing_01",
      "deviceType": "THING",
      "templateId": "83d95d04-8629-46e9-b1da-530b0e6d2cf6",
      "enrollmentState": "REGISTERED",
      "parentId": "413d5b55-ec4a-4026-a89a-7eb3986f8f4e",
      "parentGatewayId": "413d5b55-ec4a-4026-a89a-7eb3986f8f4e",
      "orgId": "618ab173-efa4-4d8a-8793-fa5377f5bd7e",
      "createdTime": 1570102596241,
      "lastUpdatedTime": 1570102596241,
      "updateVersion": 1,
      "id": "12c6006e-a27f-47eb-8a42-1313f3edd57f"
    }
  ],
  "pageInfo": {
    "totalPages": 1,
    "page": 1,
    "pageSize": 1000,
    "totalElements": 2
  }
}

Update Device System Properties

Header 
Authorization : {{DeviceAccessToken}}
Required Permissions

You must have the Edit System Properties permission to perform this operation.

API
/api/devices/{id}/system-properties
Method
POST
Required Parameters
Name Description
remove

string

System property names to be removed.
upsert

string

System property names to be inserted or updated.
  • name
  • value
Input Example 
{  
   "upsert":[  
      {  
         "name":"os-machine",
         "value":"Windows"
      },
      {  
         "name":"version",
         "value":"123"
      }
   ],
   "remove":[  
      "model",
      "make"
   ]
}
Response 
{}

Update Device Custom Properties

Required Permissions

You must have the Edit Custom Properties permission to perform this operation.

API
/api/devices/{id}/custom-properties
Method
POST
Required Parameters
Name Description
remove

string

Custom property names to be removed.
upsert

string

Custom property names to be inserted or updated.
  • name
  • value
Input Example 
{  
   "upsert":[  
      {  
         "name":"os-machine",
         "value":"Windows"
      },
      {  
         "name":"version",
         "value":"123"
      }
   ],
   "remove":[  
      "model",
      "make"
   ]
}
Response 
{}

Update Custom Property on Multiple Devices

Required Permissions

You must have the Edit Custom Properties permission to perform this operation.

API
https://{{URL}}:{{PORT}}/api/devices
Method
PUT
Required Parameters
Name Description
Query param: action -> UPDATE_CUSTOM_PROPERTY

string

Sample Request for Property Addition or Edit 
 {
	"filter": 
          {
            "deviceId": [
                "3c499010-9e7b-4037-b024-d89a3f0b29eb",
                "ca4417a7-6b45-4bff-8524-0bdc3342663c",
                "42a6884c-7c7f-4b9f-9050-e4616cef5677",
                "04345c2b-2787-4cf0-852c-3816ec23513f",
                "56788d57-9f4b-4e07-84d6-afb4526c7e63"
               ]
           },
	"property" : 
          {
		"upsert":[{"name":"test1","value":"123"},{"name":"test2","value":"456"}]
	  }
}
Sample Request for Property Deletion 
 "filter": 
          {
            "deviceId": [
                "3c499010-9e7b-4037-b024-d89a3f0b29eb",
                "ca4417a7-6b45-4bff-8524-0bdc3342663c",
                "42a6884c-7c7f-4b9f-9050-e4616cef5677",
                "04345c2b-2787-4cf0-852c-3816ec23513f",
                "56788d57-9f4b-4e07-84d6-afb4526c7e63"
               ]
           },
	"property" : 
          {
		"remove":["test1", "test2"]
	  }
}
Response 
{"taskId":"68560ff6-977f-4b23-bc5c-999d8c8da08y"}

Update Agent

Required Permissions

You must have the Update Agent permission to perform this operation.

API
/api/devices/{id}/update-agent
Method
PUT
Input Example 
{}
Response 
{}

Create a Device Template

Required Permissions

You must have the Create Device Template permission to perform this operation.

API
/api/device-templates
Method
POST
Parameters
Name Description
name

string

Template name. Must be unique for the tenant. (Required)
deviceType

string

Device type for which the template is created (Required):
  • GATEWAY
  • THING
systemProperties

array

name: Property name key.

customProperties

array

  • name: Property name key.
  • value: Default value.
allowedMetrics

array

  • name: Metric name key.
  • value: Metric value type.
    • INT64
    • DOUBLE
    • STRING
    • BOOLEAN
  • unit: Unit of metric that is collected from the IoTC Agent.
allowedCommands

array

Allowed commands.
  • command: The supported command types are:
    • SSH
    • REBOOT
    • FILE_UPLOAD
    • EXECUTE
    • CLIENT_EXECUTE - Supported on both gateway and Thing templates.
  • name: Name of the command.
  • asroot: The command is run as root.
  • argument: The required arguments to run the command.
  • execPath: The executable path required for custom commands.
  • clientId: The client ID required for client commands.
childTemplates

array

Allowed templates.
enrollmentProvider

string

Available only on gateway templates.

 The enrollment provider (Required):
  • providerConfig: Enrollment provider property configuration.
  • type: Enrollment provider type.
    • JWT_NATIVE 
      "enrollmentProvider":{"type":"JWT_NATIVE","providerConfig":"{\"expiryTime\":57600}"
    • PROPERTY_NATIVE
      "enrollmentProvider": {"type": "PROPERTY_NATIVE", "providerConfig": "{\"identityKey\":\"DeviceKey\"}"
    • TPM_NATIVE 
      "enrollmentProvider":{"type":"TPM_NATIVE","providerConfig":"{}"}
    • BASIC
      "enrollmentProvider":{"type": "BASIC","providerConfig": ""}

The property configuration changes according to the property type.

settings

array

Available only on gateway templates.

 Device template settings:
  • commandFetchIntervalSeconds: The interval to fetch commands in seconds. The maximum value for the command fetch interval is 43200 seconds. The minimum value is 10 seconds and the default value for the command fetch interval is 30 seconds. If the time interval is not in the minimum value range, an error message is displayed.
  • maxNumberOfClients: The maximum number of clients allowed.
  • agentLogLevel: The log level to collect VMware Pulse IoTC Agent logs.
  • metricsIntervalSeconds: The interval to collect metrics in seconds. The minimum value for the metrics interval is 60 seconds and the default value for the metric interval is 300 seconds. If the time interval is not in the minimum value range, an error message is displayed.
  • grpcEnabled: Whether GPRC is enabled or not.
  • serverRequestTimeoutSecond: Timeout in seconds after which the request from the VMware Pulse IoTC Agent to the server will timeout.
  • networkBandwidth: The maximum network bandwidth allowed on the device for the IoTC Agent. The data rate is in Bytes per second (B/s). The value 0 denotes unlimited network bandwidth
Input Example
Gateway Template Request 
{  
   "name":"Gateway_01",
   "deviceType":"GATEWAY",
   "systemProperties":[  
      {  
         "name":"os-sysname"
      },
      {  
         "name":"os-machine"
      },
      {  
         "name":"os-release"
      },
      {  
         "name":"ssh"
      },
      {  
         "name":"bus-size"
      }
   ],
   "customProperties":[  
      {  
         "name":"location",
         "value":"KM"
      }
   ],
   "allowedMetrics":[  
      {  
         "name":"CPU-Usage",
         "displayName":"CPU-Usage",
         "valueType":"DOUBLE",
         "displayUnit":"%"
      },
      {  
         "name":"Memory-Usage",
         "displayName":"Memory-Usage",
         "valueType":"DOUBLE",
         "displayUnit":"%"
      },
      {  
         "name":"Disk-Usage",
         "displayName":"Disk-Usage",
         "valueType":"DOUBLE",
         "displayUnit":"%"
      }
   ],
   "allowedCommands":[  
      {  
         "command":"EXECUTE",
         "name":"CREATE_NEW_FILE_NON_ROOT",
         "arguments":[  
            {  
               "name":"test123",
               "value":[  
                  "/opt/vmware/iotc-agent/NewFile_NonRoot"
               ],
               "type":"STRING"
            }
         ],
         "asRoot":false,
         "execPath":"/bin/touch"
      },
      {  
         "command":"SSH",
         "name":"SSH",
         "arguments":[  
            {  
               "name":"arg0",
               "value":[  
                  "enable"
               ],
               "type":"STRING"
            }
         ],
         "asRoot":true
      },
      {  
         "command":"REBOOT",
         "name":"REBOOT",
         "asRoot":true
      },
      {  
         "command":"FILE_UPLOAD",
         "name":"File_single",
         "arguments":[  
            {  
               "name":"arg0",
               "value":[  
                  "/root/10MB_syslog"
               ],
               "type":"STRING"
            }
         ],
         "asRoot":true
      },
      {  
         "name":"ints",
         "command":"CLIENT_EXECUTE",
         "arguments":[  
            {  
               "name":"ints",
               "value":[  
                  1234
               ],
               "type":"INT64"
            }
         ],
         "execPath":"/usr/bin/touch",
         "clientId":"com.vmware.client.default"
      }
   ],
   "enrollmentProvider":{  
      "type":"JWT_NATIVE",
      "providerConfig":"{\"expiryTime\":30}"
   },
   "settings":[  
      {  
         "category":"iotc-agent",
         "settings":{  
            "commandFetchIntervalSeconds":30,
            "maxNumberOfClients":6,
            "agentLogLevel":6,
            "metricsIntervalSeconds":60,
            "grpcEnabled":1,
	     "serverRequestTimeoutSecond": 300
	     "networkBandwidth": 0	
         }
      }
   ],
   "childTemplates":[  
      "1234",
      "4567"
   ]
}
Thing Template Request 
{  
   "name":"Thing_03",
   "deviceType":"THING",
   "systemProperties":[  
      {  
         "name":"os-sysname"
      }
   ],
   "customProperties":[  
      {  
         "name":"location",
         "value":"KM"
      }
   ],
   "allowedMetrics":[  
      {  
         "name":"CPU",
         "displayName":"CPU",
         "valueType":"INT64",
         "displayUnit":"%"
      }
   ],
   "allowedCommands":[  
      {  
         "name":"ints",
         "command":"CLIENT_EXECUTE",
         "arguments":[  
            {  
               "name":"ints",
               "value":[  
                  1234
               ],
               "type":"INT64"
            }
         ],
         "execPath":"/usr/bin/touch",
         "clientId":"com.vmware.client.default"
      }
   ],
   "childTemplates":[  
      "1234",
      "4567"
   ]
}
Response 
{
"id": "string"
}

Update a Device Template

Required Permissions

You must have the Edit Device Template permission to perform this operation.

API
/api/device-templates/{id}
Method
PUT
Parameters
Name Description
name

string

Template name. Must be unique for the tenant. (Required)
deviceType

string

Device type for which the template is created (Required):
  • GATEWAY
  • THING
systemProperties

array

name: Property name key.

customProperties

array

  • name: Property name key.
  • value: Default value.
allowedMetrics

array

  • name: Metric name key.
  • value: Metric value type.
    • INT64
    • DOUBLE
    • STRING
    • BOOLEAN
  • unit: Unit of metric that is collected from the IoTC Agent.
allowedCommands

array

Allowed commands.
  • command: The supported command types are:
    • SSH
    • REBOOT
    • FILE_UPLOAD
    • EXECUTE
    • CLIENT_EXECUTE - Supported on both gateway and Thing templates.
  • name: Name of the command.
  • asroot: The command is run as root.
  • argument: The required arguments to run the command.
  • execPath: The executable path required for custom commands.
  • clientId: The client ID required for client commands.
childTemplates

array

Allowed templates.
enrollmentProvider

string

Available only on gateway templates.

 The enrollment provider (Required):
  • providerConfig: Enrollment provider property configuration.
  • type: Enrollment provider type.
    • JWT_NATIVE 
      "enrollmentProvider":{"type":"JWT_NATIVE","providerConfig":"{\"expiryTime\":57600}"
    • PROPERTY_NATIVE
      "enrollmentProvider": {"type": "PROPERTY_NATIVE", "providerConfig": "{\"identityKey\":\"DeviceKey\"}"
    • TPM_NATIVE 
      "enrollmentProvider":{"type":"TPM_NATIVE","providerConfig":"{}"}
    • BASIC
      "enrollmentProvider":{"type": "BASIC","providerConfig": ""}

The property configuration changes according to the property type.

settings

array

Available only on gateway templates.

 Device template settings:
  • commandFetchIntervalSeconds: The interval to fetch commands in seconds. The maximum value for the command fetch interval is 43200 seconds. The minimum value is 10 seconds and the default value for the command fetch interval is 30 seconds. If the time interval is not in the minimum value range, an error message is displayed.
  • maxNumberOfClients: The maximum number of clients allowed.
  • agentLogLevel: The log level to collect VMware Pulse IoTC Agent logs.
  • metricsIntervalSeconds: The interval to collect metrics in seconds. The minimum value for the metrics interval is 60 seconds and the default value for the metric interval is 300 seconds. If the time interval is not in the minimum value range, an error message is displayed.
  • grpcEnabled: Whether GPRC is enabled or not.
  • serverRequestTimeoutSecond: Timeout in seconds after which the request from the VMware Pulse IoTC Agent to the server will timeout.
  • networkBandwidth: The maximum network bandwidth allowed on the device for the IoTC Agent. The data rate is in Bytes per second (B/s). The value 0 denotes unlimited network bandwidth.
Input Example
Gateway Template Request 
{  
   "systemProperties":[  
      {  
         "name":"os-sysname"
      },
      {  
         "name":"os-machine"
      },
      {  
         "name":"os-release"
      },
      {  
         "name":"ssh"
      },
      {  
         "name":"bus-size"
      }
   ],
   "customProperties":[  
      {  
         "name":"location",
         "value":"KM"
      }
   ],
   "allowedMetrics":[  
      {  
         "name":"CPU-Usage",
         "displayName":"CPU-Usage",
         "valueType":"DOUBLE",
         "displayUnit":"%"
      },
      {  
         "name":"Memory-Usage",
         "displayName":"Memory-Usage",
         "valueType":"DOUBLE",
         "displayUnit":"%"
      },
      {  
         "name":"Disk-Usage",
         "displayName":"Disk-Usage",
         "valueType":"DOUBLE",
         "displayUnit":"%"
      }
   ],
   "allowedCommands":[  
      {  
         "command":"EXECUTE",
         "name":"CREATE_NEW_FILE_NON_ROOT",
         "arguments":[  
            {  
               "name":"test123",
               "value":[  
                  "/opt/vmware/iotc-agent/NewFile_NonRoot"
               ],
               "type":"STRING"
            }
         ],
         "asRoot":false,
         "execPath":"/bin/touch"
      },
      {  
         "command":"SSH",
         "name":"SSH",
         "arguments":[  
            {  
               "name":"arg0",
               "value":[  
                  "enable"
               ],
               "type":"STRING"
            }
         ],
         "asRoot":true
      },
      {  
         "command":"REBOOT",
         "name":"REBOOT",
         "asRoot":true
      },
      {  
         "command":"FILE_UPLOAD",
         "name":"File_single",
         "arguments":[  
            {  
               "name":"arg0",
               "value":[  
                  "/root/10MB_syslog"
               ],
               "type":"STRING"
            }
         ],
         "asRoot":true
      },
      {  
         "name":"ints",
         "command":"CLIENT_EXECUTE",
         "arguments":[  
            {  
               "name":"ints",
               "value":[  
                  1234
               ],
               "type":"INT64"
            }
         ],
         "execPath":"/usr/bin/touch",
         "clientId":"com.vmware.client.default"
      }
   ],
   "enrollmentProvider":{  
      "type":"JWT_NATIVE",
      "providerConfig":"{\"expiryTime\":30}"
   },
   "settings":[  
      {  
         "category":"iotc-agent",
         "settings":{  
            "commandFetchIntervalSeconds":30,
            "maxNumberOfClients":6,
            "agentLogLevel":6,
            "metricsIntervalSeconds":60,
            "grpcEnabled":1,
	     "serverRequestTimeoutSecond": 300
	     "networkBandwidth": 0
         }
      }
   ],
   "childTemplates":[  
      "1234",
      "4567"
   ]
}
Thing Template Request 
{  
   "systemProperties":[  
      {  
         "name":"os-sysname"
      }
   ],
   "customProperties":[  
      {  
         "name":"location",
         "value":"KM"
      }
   ],
   "allowedMetrics":[  
      {  
         "name":"CPU",
         "displayName":"CPU",
         "valueType":"INT64",
         "displayUnit":"%"
      }
   ],
   "allowedCommands":[  
      {  
         "name":"ints",
         "command":"CLIENT_EXECUTE",
         "arguments":[  
            {  
               "name":"ints",
               "value":[  
                  1234
               ],
               "type":"INT64"
            }
         ],
         "execPath":"/usr/bin/touch",
         "clientId":"com.vmware.client.default"
      }
   ],
   "childTemplates":[  
      "1234",
      "4567"
   ]
}
Response 
{
"id": "string"
}

Get a Device Template by ID

Required Permissions

You must have the View Device Template permission to perform this operation.

API
/api/device-templates/{id}
Method
GET
Required Parameters
Name Description
id

string

Device template ID.
Response 
{
    "imageDetails": [{
        "imageUrl": "string",
        "id": "string",
        "sourceType": "string"
    }],
    "name": "string",
    "systemProperties": [{
        "name": "string"
    }],
    "allowedMetrics": [{
        "displayUnit": "string",
        "displayName": "string",
        "name": "string",
        "valueType": "UNKNOWN_VALUE_TYPE"
    }],
    "updateVersion": 0,
    "enrollmentProvider": {
        "providerConfig": "string",
        "type": "string"
    },
    "deviceType": "UNKNOWN_TYPE",
    "allowedCommands": [{
        "command": "string",
        "name": "string",
        "arguments": [{
            "name": "string",
            "value": [
                "string"
            ],
            "type": "string"
        }],
        "asRoot": true,
        "execPath": "string"
    }],
    "customProperties": [{
        "name": "string",
        "value": "string"
    }],
    "settings": [{
        "category": "string",
        "settings": {
            "commandFetchIntervalSeconds": long,
            "maxNumberOfClients": long,
            "agentLogLevel": long,
            "metricsIntervalSeconds": long,
            "grpcEnabled": long,
	     "serverRequestTimeoutSecond": long
	     "networkBandwidth": 0		
        },
        "finalSettings": {}
    }],
    "lastUpdatedTime": "string",
    "createdTime": "string",
    "orgId": "string",
    "id": "string",
    "childTemplates": [
        "string"
    ]
}

Delete a Device Template by ID

Required Permissions

You must have the Delete Device Template permission to perform this operation.

API
/api/device-templates/{id}
Method
DELETE
Required Parameters
Name Description
id

string

Device template ID.
Response 
{}

List Device Templates

Required Permissions

You must have the View Device Template permission to perform this operation.

API
/api/device-templates
Method
GET
Optional Parameters
Name Description
id

array

List of device template IDs.
name

string

Template name.
deviceType

string

Device type:
  • GATEWAY
  • THING
page.number

int32

Page number.
page.size

string

Page size.
exactName

string

Exact name of the search.
queryType SHOW_CURRENT, SHOW_ANCESTORS,SHOW_DESCENDANTS or SHOW_ALL
Response 
{
  "templates": [
    {
      "imageDetails": [
        {
          "imageUrl": "string",
          "id": "string",
          "sourceType": "string"
        }
      ],
      "name": "string",
      "systemProperties": [
        {
          "name": "string"
        }
      ],
      "allowedMetrics": [
        {
          "displayUnit": "string",
          "displayName": "string",
          "name": "string",
          "valueType": "UNKNOWN_VALUE_TYPE",
          
        }
      ],
      "updateVersion": 0,
      "enrollmentProvider": {
        "providerConfig": "string",
        "type": "string"
      },
      "deviceType": "UNKNOWN_TYPE",
      "allowedCommands": [
        {
          "command": "string",
          "name": "string",
          "asRoot": true,
          "arguments": [
            "string"
          ]
        }
      ],
      "customProperties": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "lastUpdatedTime": "string",
      "createdTime": "string",
      "orgId": "string",
      "id": "string",
      "childTemplates": [
        "string"
      ]
    }
  ],
  "pageInfo": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  }
}

Get Property Keys From Device Templates

Required Permissions

You must have the View Device permission to perform this operation.

API
https://{{URL}}:{{PORT}}/api/devices/keys
Method
GET
Optional Parameters
Name Description
id Device template ID.
name

string

Property key name.
maxSize

string

Number of keys to be returned in the response.
Response 
"keys": [
          {
            "key": "os-release",
            "keyQualifier": "systemProperties"
        },
         {
            "key": "ssh",
            "keyQualifier": "systemProperties"
        }
    ]
}

Get Property Values From Device

Required Permissions

You must have the View Device permission to perform this operation.

API
https://{{URL}}:{{PORT}}/api/devices/keys/values
Method
GET
Mandatory Query Parameters
Name Description
keyQualifier Allowed values: customProperties/systemProperties/device
key

string

If keyQualifier is set to device then the key should be either name/id/parentGatewayId/ deviceType/templateId/enrollmentState
Optional Parameters
Name Description
name

string

Property value.
maxSize

string

Number of keys to be returned in the response.
Request 
https://{{URL}}:{{PORT}}/api/devices/keys/values?keyQualifier=systemProperties&key=ssh&name=enable
https://{{URL}}:{{PORT}}/api/devices/keys/values?maxSize=10&keyQualifier=device&key=name
Response 
{
    "values": [
        {
            "key": "name",
            "keyQualifier": "device",
            "values": [
                {
                    "value": "test1",
                    "count": 1
                }
            ]
        }
    ]
}

Get Pending Commands

Required Permissions

You must have the Get Device Command permission to perform this operation.

API
/api/devices/{device_id}/commands
Method
GET
Required Parameters
Name Description
deviceId

string

Device ID.
Response 
{
	"commandMessage": [{
		"lastUpdatedTime": "string",
		"asRoot": true,
		"command": "string",
		"arguments": [{
			"name": "string",
			"value": [
				"string"
			],
			"type": "string"
		}],
		"createdTime": "string",
		"commandId": "string",
		"deviceId": "string",
		"name": "string"
	}]
}"

Invoke Device Command

Required Permissions

You must have the Send Device Command permission to perform this operation.

API
/api/devices/{device_id}/commands
Method
POST
Required Parameters
Name Description
deviceId

string

Device ID.
Invoke Command Examples
SSH 
{"name":"SSH_EN","command":"SSH","arguments":[{"name":"args","type":"STRING","value":["enable"]}]}
REBOOT 
{"name":"REBOOT","command":"REBOOT","arguments":[]}
FILE_UPLOAD 
{"name":"UploadFile","command":"FILE_UPLOAD","arguments":[{"name":"test","type":"STRING","value":["/root/test.log"]}]}
EXECUTE 
{"name":"create_file","command":"EXECUTE","arguments":[{"name":"test","type":"STRING","value":["/root/test.txt"]}]}
CLIENT_EXECUTE 
{"name":"ExecuteClientCmd","command":"CLIENT_EXECUTE","arguments":[{"name":"ints","type":"STRING","value":["1234”]}]}
Response 
{
  "commandId": "string"
}

Update Device Command Status

Required Permissions

You must have the Edit Device Command permission to perform this operation.

API
/api/devices/{device_id}/commands
Method
PUT
Required Parameters
None
Input Example 
{
    "commandResponse": [
        {
            "commandId": "string",
            "status": "EXECUTED/FAILED",
            "response": "string"
        }
    ]
}
Response 
{
  "commandIds": [
    "string"
  ]
}

List Device Commands

Required Permissions

You must have the Get Device Command permission to perform this operation.

API
/api/devices/commands
Method
GET
Optional Parameters
Name Description
deviceId

string

Device ID.
page.number

int32

Page number.
page.size

string

Page size.
commandName

string

 Command name.
commandStatus

string

 Command status.
commandType

string

 Command type.
commandId

string

 Command ID
Response 
{
  "commands": [
    {
      "status": "string",
      "name": "string",
      "lastUpdatedTime": "string",
      "asRoot": true,
      "response": "string",
      "command": "string",
      "arguments": [
        "string"
      ],
      "createdTime": "string",
      "commandId": "string",
      "deviceId": "string"
    }
  ],
  "pageInfo": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  }
}

Create Device Credential

Required Permissions

You must have the Create Device Credential permission to perform this operation.

API
api/device-credentials/{id}
Method
POST
Input Example
JWT_NATIVE 
{}
PROPERTY_NATIVE 
{"requestParams":"{\"DeviceKey\":\"1234\"}"}
TPM_NATIVE 
{"requestParams":"{\"tpm_ek\":\"123456\"}"}
Response 
{
  "credentials": "string"
}

Get Device Token

Required Permissions

You must have the Get Device Token permission to perform this operation.

API
/api/device-tokens
Header
Set the header based on the type of enrollment you want to perform:
  • Basic Enrollment:
    Authorization - {{UserAcccessToken}}
Accept - application/json;api-version={{VERSION}}
Content-Type - application/json
  • Token Based Enrollment:
    x-device-auth - {{device-credentials}}
Accept - application/json;api-version={{VERSION}}
Content-Type - application/json

Enter the device credential that you created in the Create Device Credential API.

Method
GET
Required Parameters
Name Description
id

string

Device ID.
Response 
{
  "deviceId": "string",
  "accessToken": "string"
}

File Upload

API
api/devices/files
Header 
Authorization: {{DeviceAccessToken}}
Content-Type: application/octet-stream
Or 
Authorization: {{DeviceAccessToken}}
Content-Type: multipart/form-data
Method
POST
Parameters
Name Description
filename

string

File name (required).
description

string

 File description (optional).
deviceId

string

 Device ID (optional).
Response 
{
"id": "string"
}

File Download

Download a file that is stored in the database.

API
api/devices/files/{fileId}
Header 
Accept: application/octet-stream
Add a Range header to specify the file size to download. For example: 
Range: bytes=100-2000
Method
GET
Response
Content of the file.

Get File Info

Get the file information.

API
api/devices/files/{fileId}/file-info
Method
GET
Response 
{
    "deviceIds": [
        "string"
    ],
    "fsId": "string",
    "name": "string",
    "size": long,
    "path": "string",
    "parentDirectory": "string",
    "isDirectory": false,
    "orgId": "string",
    "createdTime": long,
    "lastUpdatedTime": long,
    "updateVersion": int,
    "createdBy": "string",
    "lastUpdatedBy": "string",
    "expireAt": long,
    "id": "string"
}"

List Files

List all the files uploaded for a device.

API
/api/devices/files
Header 
Authorization - {{UserAcccessToken}}
Accept - application/json;api-version={{VERSION}}
Content-Type - application/json
Method
GET
Parameters
Name Description
page.number

int32

Page number.
page.size

string

 Page size.
fileId

string

 File ID.
name

string

 Name of the file.
Response 
{ 
   "files":[ 
      { 
         "expireAt":1568022685000,
         "deviceIds":[ 
            "35137adb-e801-4238-a2dc-ea9c06857aa2"
         ],
         "name":"FileExpiryTest12.txt",
         "path":"/devices/3fac7479-fb77-4c7b-9454-805649aed3d9",
         "isDirectory":false,
         "orgId":"9480f326-aa95-41bd-886e-25e574f79f09",
         "createdTime":1568022565351,
         "lastUpdatedTime":1568022565351,
         "createdBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",
         "lastUpdatedBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",
         "id":"3fac7479-fb77-4c7b-9454-805649aed3d9"
      },
      { 
         "expireAt":1568022680000,
         "deviceIds":[ 
            "35137adb-e801-4238-a2dc-ea9c06857aa2"
         ],
         "name":"FileExpiryTest11.txt",
         "path":"/devices/bd6164d7-07ba-4227-9134-1fd0dae58aea",
         "isDirectory":false,
         "orgId":"9480f326-aa95-41bd-886e-25e574f79f09",
         "createdTime":1568022560351,
         "lastUpdatedTime":1568022560351,
         "createdBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",
         "lastUpdatedBy":"35137adb-e801-4238-a2dc-ea9c06857aa2",
         "id":"bd6164d7-07ba-4227-9134-1fd0dae58aea"
      }
   ],
   "pageInfo":{ 
      "totalPages":1,
      "page":1,
      "pageSize":20,
      "totalElements":2
   }
}

Delete File

delete files.

API
/api/devices/files
Method
DELETE
Header 
Authorization - {{UserAcccessToken}}
Accept - application/json;api-version={{VERSION}}

Advanced Filter

Use the advanced filter API to search for devices based on certain property values.

API
/api/devices/advanced-filter
Method
POST
Input Example 
{  
   "property":[  
      {  
         "name":"color",
         "operatorValue":[  
            {  
               "operator":"EQUAL_TO",
               "value":"red"
            }
         ],
         "type":"CUSTOM_PROPERTY"
      }
   ]
}
Response

Returns the list of devices that satisfy the property filter criteria.

{  
   "devices":[  
      {  
         "name":"device3",
         "templateName":"Default Gateway Template",
         "deviceType":"GATEWAY",
         "templateId":"870bbefe-4796-448a-a92a-0c83989b480c",
         "systemProperties":[  
            {  
               "name":"os-sysname",
               "value":""
            },
            {  
               "name":"os-machine",
               "value":""
            },
            {  
               "name":"os-release",
               "value":""
            },
            {  
               "name":"ssh",
               "value":""
            },
            {  
               "name":"iotc-agent-version",
               "value":""
            }
         ],
         "customProperties":[  
            {  
               "name":"color",
               "value":"red"
            },
            {  
               "name":"qr-code",
               "value":"qr-code-value"
            }
         ],
         "enrollmentState":"REGISTERED",
         "parentGatewayId":"cf37abdf-6352-424e-ae31-117173077d1e",
         "orgId":"a085e01b-b561-4239-89f1-802df460405a",
         "createdTime":1566539088764,
         "lastUpdatedTime":1566539088764,
         "updateVersion":1,
         "id":"cf37abdf-6352-424e-ae31-117173077d1e"
      },
      {  
         "name":"device2",
         "templateName":"Default Gateway Template",
         "deviceType":"GATEWAY",
         "templateId":"870bbefe-4796-448a-a92a-0c83989b480c",
         "systemProperties":[  
            {  
               "name":"os-sysname",
               "value":""
            },
            {  
               "name":"os-machine",
               "value":""
            },
            {  
               "name":"os-release",
               "value":""
            },
            {  
               "name":"ssh",
               "value":""
            },
            {  
               "name":"iotc-agent-version",
               "value":""
            }
         ],
         "customProperties":[  
            {  
               "name":"color",
               "value":"red"
            },
            {  
               "name":"qr-code",
               "value":"qr-code-value"
            }
         ],
         "enrollmentState":"REGISTERED",
         "parentGatewayId":"1599653f-9c03-4eaa-b608-c66e32f84b1d",
         "orgId":"a085e01b-b561-4239-89f1-802df460405a",
         "createdTime":1566539081748,
         "lastUpdatedTime":1566539081748,
         "updateVersion":1,
         "id":"1599653f-9c03-4eaa-b608-c66e32f84b1d"
      },
      {  
         "name":"device1",
         "templateName":"Default Gateway Template",
         "deviceType":"GATEWAY",
         "templateId":"870bbefe-4796-448a-a92a-0c83989b480c",
         "systemProperties":[  
            {  
               "name":"iotc-agent-version",
               "value":""
            },
            {  
               "name":"ssh",
               "value":""
            },
            {  
               "name":"os-release",
               "value":""
            },
            {  
               "name":"os-machine",
               "value":""
            },
            {  
               "name":"os-sysname",
               "value":""
            }
         ],
         "customProperties":[  
            {  
               "name":"color",
               "value":"red"
            }
         ],
         "enrollmentState":"REGISTERED",
         "parentGatewayId":"05cf8b0b-b3ae-486c-87d3-80f67868668a",
         "orgId":"a085e01b-b561-4239-89f1-802df460405a",
         "createdTime":1566538985229,
         "lastUpdatedTime":1566539073281,
         "updateVersion":2,
         "id":"05cf8b0b-b3ae-486c-87d3-80f67868668a"
      }
   ],
   "pageInfo":{  
      "totalPages":1,
      "page":1,
      "pageSize":10,
      "totalElements":3
   }
}

Invoke Bulk Command

Send commands to multiple devices.

API
/api/devices
Method
PUT
Header 
Authorization - {{UserAcccessToken}}
Accept - application/json;api-version={{VERSION}}
Content-Type - application/json
Parameters
Name Description
action

string

SEND_COMMAND
Input Example 
{ 
   "filter":{ 
      "deviceId":[ 
         "f32c1dcf-52ce-4d53-b558-6ca7fba60f86",
         "f32c1dcf-52ce-4d53-b558-6ca7fba60f84",
         "f32c1dcf-52ce-4d53-b558-6ca7fba60f87"
      ]
   },
   "command":[ 
      { 
         "command":"SSH",
         "name":"SSH_ENABLE",
         "arguments":[ 
            { 
               "name":"args",
               "value":[ 
                  "enable"
               ],
               "type":"STRING"
            }
         ]
      }
   ]
}
Sample Response 
{"taskId":"68560ff6-977f-4b23-bc5c-999d8c8da08e"}

Invoke Bulk Agent Update

Send agent update command to multiple devices.

API
/api/devices
Method
PUT
Header 
Authorization - {{UserAcccessToken}}
Accept - application/json;api-version={{VERSION}}
Content-Type - application/json
Parameters
Name Description
action

string

UPDATE_AGENT
Input Example 
{
    "filter": {
        "deviceId": [
            "ca4417a7-6b45-4bff-8524-0bdc3342663c",
            "42a6884c-7c7f-4b9f-9050-e4616cef5677"
        ]
    }
}
Sample Response 
{"taskId":"68560ff6-977f-4b23-bc5c-999d8c8da08e"}

Get Task Info

Get information about a task.

API
/api/tasks/{taskId}
Method
GET
Header 
Authorization - {{UserAcccessToken}}
Accept - application/json;api-version={{VERSION}}
Content-Type - application/json
Sample Response 
{ 
   "id":"ef996658-6111-43bd-bdfc-9d1fa4448ee0",
   "fqId":"ef996658-6111-43bd-bdfc-9d1fa4448ee0",
   "parentId":"",
   "queueName":"devicemgmt",
   "type":"DEVICE_BULK_INVOKE_COMMAND_TASK",
   "version":"1.0",
   "data":{ 
      "filter":{ 
         "deviceId":[ 
            "27e9963f-4f95-4206-9eb2-1b66739d1b4b",
            "42e59eb0-f44b-4d6c-af68-a4077dab8731",
            "cd340f6a-d862-4cc1-bd34-e919729daa20",
            "ebd14b77-95f2-490c-86d2-197b75f5ed4a",
            "0cd13e61-a136-4d19-afc2-b559cd0598f9"
         ]
      },
      "command":[ 
         { 
            "name":"UPLOAD_AGENT_INSTALL_LOG_FILE",
            "command":"FILE_UPLOAD",
            "arguments":[ 
               { 
                  "name":"arg0",
                  "type":"STRING",
                  "value":[ 
                     "/var/log/vmware/iotc-agent/install.log"
                  ]
               }
            ]
         }
      ]
   },
   "context":{ 
      "userName":"[email protected]",
      "userId":"d2bcaddf-7b2f-4776-95db-25f92d4f8101",
      "orgId":"b5abe95e-2cef-4caa-ab6c-3745f0c482bd",
      "deviceId":null,
      "system":false,
      "device":false,
      "traceId":"07244fa664378efa69c62f0bfe3cd4e3"
   },
   "state":"REQUEUED",
   "prevState":"COMMAND_EXECUTION_IN_PROGRESS",
   "result":{ 
      "summary":{ 
         "skipped":0,
         "pending":0,
         "executed":5,
         "failed":0,
         "total":5
      },
      "details":[ 
         { 
            "deviceId":"27e9963f-4f95-4206-9eb2-1b66739d1b4b",
            "status":"EXECUTED"
         },
         { 
            "deviceId":"42e59eb0-f44b-4d6c-af68-a4077dab8731",
            "status":"EXECUTED"
         },
         { 
            "deviceId":"cd340f6a-d862-4cc1-bd34-e919729daa20",
            "status":"EXECUTED"
         },
         { 
            "deviceId":"ebd14b77-95f2-490c-86d2-197b75f5ed4a",
            "status":"EXECUTED"
         },
         { 
            "deviceId":"0cd13e61-a136-4d19-afc2-b559cd0598f9",
            "status":"EXECUTED"
         }
      ]
   },
   "lastUpdatedByTaskManager":"devicemgmt-10.92.183.251",
   "availableAt":1567517299638,
   "createdTime":1567515912843,
   "lastUpdatedTime":1567517269639,
   "notifyParentOnComplete":false,
   "failTaskOnException":true,
   "name":"Device Command - UPLOAD_AGENT_INSTALL_LOG_FILE",
   "numOfSubTasks":1,
   "numOfSubTasksCompleted":1,
   "numOfSubTasksFailed":0
}