Mistake on this page? Email us

Device Directory API

This is the API Documentation for the Device Directory service.
Version: 3
Host: https://api.us-east-1.mbedcloud.com

Endpoints

Default

post /v3/devices/
Create a device Show more Show less
Create a new device.
Request body
Device DeviceDataPostRequest (required)
Body Parameter
Return type
Example data
Content-Type: application/json
{
  "enrolment_list_timestamp" : "2017-05-22T12:37:55.576563Z",
  "description" : "description",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "device_execution_mode" : 0,
  "custom_attributes" : "{ 'key': 'value' }",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "auto_update" : true,
  "state" : "unenrolled",
  "id" : "00000000000000000000000000000000",
  "mechanism" : "connector",
  "deployment" : "",
  "device_key" : "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00",
  "mechanism_url" : "",
  "manifest" : "",
  "endpoint_name" : "00000000-0000-0000-0000-000000000000",
  "manifest_timestamp" : "2017-05-22T12:37:55.576563Z",
  "groups" : [ "00000000000000000000000000000000" ],
  "serial_number" : "00000000-0000-0000-0000-000000000000",
  "connector_expiration_date" : "2000-01-23",
  "endpoint_type" : "",
  "host_gateway" : "",
  "account_id" : "00000000000000000000000000000000",
  "bootstrapped_timestamp" : "2017-05-22T12:37:55.576563Z",
  "bootstrap_expiration_date" : "2000-01-23",
  "vendor_id" : "00000000-0000-0000-0000-000000000000",
  "firmware_checksum" : "0000000000000000000000000000000000000000000000000000000000000000",
  "name" : "00000000-0000-0000-0000-000000000000",
  "device_class" : "",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "ca_id" : "00000000000000000000000000000000",
  "deployed_state" : "development",
  "object" : "device"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Device created. DeviceData
400 Validation error: The data used to create the device did not validate.
401 Not authenticated.
403 Account limit reached. Could not create device.
409 Unique-constrained fields are used by other resources.
delete /v3/devices/{id}/
Delete a device. Show more Show less
Delete device. Only available for devices with a developer certificate. Attempts to delete a device with a production certicate will return a 400 response.
Path parameters
id (required)
Path Parameter
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Device deleted.
400 Bad Request.
401 Not authenticated.
404 Unable to delete device because it can't be found.
get /v3/device-events/
List all device events. Show more Show less
List all device events for an account.
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
order (optional)
Query Parameter — The order of the records based on creation time, ASC or DESC; by default ASC.
after (optional)
Query Parameter — The ID of The item after which to retrieve the next page.
include (optional)
Query Parameter — Comma-separated list of data fields to return. Currently supported: total_count
filter (optional)
Query Parameter

URL encoded query string parameter to filter returned data.

Filtering

?filter={URL encoded query string}

The query string is made up of key/value pairs separated by ampersands. So for a query of key1=value1&key2=value2&key3=value3 this would be encoded as follows: ?filter=key1%3Dvalue1%26key2%3Dvalue2%26key3%3Dvalue3

Filterable fields:

The below table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
date_time
description  
id  
device_id  
event_type  
state_change  
 

The examples below show the queries in unencoded form.

By id:

id={id}

By state change:

state_change=[True|False]

By event type:

event_type={value}

On date-time fields:

Date-time fields should be specified in UTC RFC3339 format YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds e.g. 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds e.g. 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened - without milliseconds and punctuation e.g. 20161130T162512Z

Date-time filtering supports three operators:

  • equality
  • greater than or equal to – field name suffixed with __gte
  • less than or equal to – field name suffixed with __lte Lower and upper limits to a date-time range may be specified by including both the __gte and __lte forms in the filter. {field name}[|__lte|__gte]={UTC RFC3339 date-time}
Multi-field example

id=0158d38771f70000000000010010038c&state_change=True&date_time__gte=2016-11-30T16:25:12.1234Z

Encoded:

?filter=id%3D0158d38771f70000000000010010038c%26state_change%3DTrue%26date_time__gte%3D2016-11-30T16%3A25%3A12.1234Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated: event_type__in=update.device.device-created,update.device.device-updated

Return type
Example data
Content-Type: application/json
{
  "data" : "[]",
  "total_count" : 1,
  "limit" : 1000,
  "after" : "null",
  "has_more" : false,
  "object" : "list",
  "order" : "DESC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. DeviceEventPage
400 Bad Request.
401 Not authenticated.
404 Unable to find page.
get /v3/device-events/{device_event_id}/
Retrieve a device event. Show more Show less
Retrieve a specific device event.
Path parameters
device_event_id (required)
Path Parameter
Return type
Example data
Content-Type: application/json
{
  "data" : {
    "campaign_id" : "00000000000000000000000000000000"
  },
  "device_id" : "00000000000000000000000000000000",
  "changes" : { },
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "Device record created",
  "event_type" : "UPD2_100",
  "date_time" : "2017-05-22T12:37:55.576563Z",
  "event_type_category" : "FAIL_MANIFEST_REJECTED",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "00000000000000000000000000000000",
  "event_type_description" : "FAIL",
  "state_change" : true,
  "object" : "device-event"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Retrieved result successfully. DeviceEventData
400 Bad Request.
401 Not authenticated.
404 Unable to find device.
get /v3/devices/
List all devices. Show more Show less
List all devices.
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
order (optional)
Query Parameter — The order of the records based on creation time, ASC or DESC; by default ASC.
after (optional)
Query Parameter — The ID of The item after which to retrieve the next page.
include (optional)
Query Parameter — Comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL encoded query string parameter to filter returned data.

Filtering

?filter={URL encoded query string}

The query string is made up of key/value pairs separated by ampersands. So for a query of key1=value1&key2=value2&key3=value3 this would be encoded as follows: ?filter=key1%3Dvalue1%26key2%3Dvalue2%26key3%3Dvalue3

Filterable fields:

The below table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
account_id  
auto_update  
bootstrap_expiration_date
bootstrapped_timestamp
ca_id  
connector_expiration_date
created_at
custom_attributes    
deployed_state  
deployment  
description  
device_class  
device_execution_mode  
device_key  
endpoint_name  
endpoint_type  
enrolment_list_timestamp
etag
firmware_checksum  
host_gateway  
id  
manifest  
manifest_timestamp
mechanism  
mechanism_url  
name  
serial_number  
state  
updated_at
vendor_id  
 

The examples below show the queries in unencoded form.

By device properties (all properties are filterable):

state=[unenrolled|cloud_enrolling|bootstrapped|registered] device_class={value}

On date-time fields:

Date-time fields should be specified in UTC RFC3339 format YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds e.g. 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds e.g. 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened - without milliseconds and punctuation e.g. 20161130T162512Z

Date-time filtering supports three operators:

  • equality
  • greater than or equal to – field name suffixed with __gte
  • less than or equal to – field name suffixed with __lte

Lower and upper limits to a date-time range may be specified by including both the __gte and __lte forms in the filter. {field name}[|__lte|__gte]={UTC RFC3339 date-time}

On device custom attributes:

custom_attributes__{param}={value} custom_attributes__tag=TAG1

Multi-field example

state=bootstrapped&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Encoded:

?filter=state%3Dbootstrapped%26created_at__gte%3D2016-11-30T16%3A25%3A12.1234Z%26created_at__lte%3D2016-11-30T00%3A00%3A00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated: state__nin=unenrolled,dergistered

Return type
Example data
Content-Type: application/json
{
  "data" : "[]",
  "total_count" : 1,
  "limit" : 1000,
  "after" : "null",
  "has_more" : false,
  "object" : "list",
  "order" : "DESC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. DevicePage
400 Bad Request.
401 Not authenticated.
404 Unable to find page.
get /v3/devicelog/
DEPRECATED: List all device events. Show more Show less
DEPRECATED: List all device events. Use /v3/device-events/ instead.
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
order (optional)
Query Parameter — The order of the records based on creation time, ASC or DESC; by default ASC.
after (optional)
Query Parameter — The ID of The item after which to retrieve the next page.
include (optional)
Query Parameter — Comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL encoded query string parameter to filter returned data.

Filtering

?filter={URL encoded query string}

The query string is made up of key/value pairs separated by ampersands. So for a query of key1=value1&key2=value2&key3=value3 this would be encoded as follows: ?filter=key1%3Dvalue1%26key2%3Dvalue2%26key3%3Dvalue3

Filterable fields:

The below table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
date_time
description  
id  
device_id  
event_type  
state_change  
 

The examples below show the queries in unencoded form.

By id:

id={id}

By state change:

state_change=[True|False]

By event type:

event_type={value}

On date-time fields:

Date-time fields should be specified in UTC RFC3339 format YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds e.g. 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds e.g. 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened - without milliseconds and punctuation e.g. 20161130T162512Z

Date-time filtering supports three operators:

  • equality
  • greater than or equal to – field name suffixed with __gte
  • less than or equal to – field name suffixed with __lte

Lower and upper limits to a date-time range may be specified by including both the __gte and __lte forms in the filter. {field name}[|__lte|__gte]={UTC RFC3339 date-time}

Multi-field example

id=0158d38771f70000000000010010038c&state_change=True&date_time__gte=2016-11-30T16:25:12.1234Z

Encoded:

?filter=id%3D0158d38771f70000000000010010038c%26state_change%3DTrue%26date_time__gte%3D2016-11-30T16%3A25%3A12.1234Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated: event_type__in=update.device.device-created,update.device.device-updated

Return type
Example data
Content-Type: application/json
{
  "data" : "[]",
  "total_count" : 1,
  "limit" : 1000,
  "after" : "null",
  "has_more" : false,
  "object" : "list",
  "order" : "DESC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful DeviceEventPage
400 Bad Request
401 Not authenticated
404 Unable to find page
get /v3/devicelog/{device_event_id}/
DEPRECATED: Retrieve a device event. Show more Show less
Retrieve device event (deprecated, use /v3/device-events/{device_event_id}/ instead).
Path parameters
device_event_id (required)
Path Parameter
Return type
Example data
Content-Type: application/json
{
  "data" : {
    "campaign_id" : "00000000000000000000000000000000"
  },
  "device_id" : "00000000000000000000000000000000",
  "changes" : { },
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "Device record created",
  "event_type" : "UPD2_100",
  "date_time" : "2017-05-22T12:37:55.576563Z",
  "event_type_category" : "FAIL_MANIFEST_REJECTED",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "00000000000000000000000000000000",
  "event_type_description" : "FAIL",
  "state_change" : true,
  "object" : "device-event"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Retrieved result successfully. DeviceEventData
400 Bad Request.
401 Not authenticated.
404 Unable to find device.
post /v3/device-queries/
Create a device query Show more Show less
Create a new device query.
Request body
Device DeviceQueryPostPutRequest (required)
Body Parameter
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "query" : "id=00000000000000000000000000000000",
  "name" : "00000000000000000000000000000000",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "00000000000000000000000000000000",
  "object" : "device-query"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Update device query created. DeviceQuery
400 Validation error: The data used to create the device query did not validate.
401 Not authenticated.
delete /v3/device-queries/{query_id}/
Delete a device query Show more Show less
Delete a device query.
Path parameters
query_id (required)
Path Parameter
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Update device query deleted.
400 Validation error: The data used to create the device query did not validate
401 Not authenticated.
404 Unable to delete update device query because it can't be found.
get /v3/device-queries/
List device queries. Show more Show less
List all device queries. The result will be paged into pages of 100.
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
order (optional)
Query Parameter — The order of the records based on creation time, ASC or DESC; by default ASC.
after (optional)
Query Parameter — The ID of The item after which to retrieve the next page.
include (optional)
Query Parameter — Comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL encoded query string parameter to filter returned data.

Filtering

?filter={URL encoded query string}

The query string is made up of key/value pairs separated by ampersands. So for a query of key1=value1&key2=value2&key3=value3 this would be encoded as follows: ?filter=key1%3Dvalue1%26key2%3Dvalue2%26key3%3Dvalue3

The below table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
created_at
etag
id  
name  
query  
updated_at
 

The examples below show the queries in unencoded form.

By device query properties (all properties are filterable):

For example: description={value}

On date-time fields:

Date-time fields should be specified in UTC RFC3339 format YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds e.g. 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds e.g. 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened - without milliseconds and punctuation e.g. 20161130T162512Z

Date-time filtering supports three operators:

  • equality
  • greater than or equal to – field name suffixed with __gte
  • less than or equal to – field name suffixed with __lte

Lower and upper limits to a date-time range may be specified by including both the __gte and __lte forms in the filter. {field name}[|__lte|__gte]={UTC RFC3339 date-time}

Multi-field example

query_id=0158d38771f70000000000010010038c&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Encoded:

filter=query_id%3D0158d38771f70000000000010010038c%26created_at__gte%3D2016-11-30T16%3A25%3A12.1234Z%26created_at__lte%3D2016-11-30T00%3A00%3A00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated: name__nin=query1,query2

Return type
Example data
Content-Type: application/json
{
  "data" : "[]",
  "total_count" : 1,
  "limit" : 1000,
  "after" : "null",
  "has_more" : false,
  "object" : "list",
  "order" : "DESC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Request successful. DeviceQueryPage
400 Bad Request.
401 Not authenticated.
404 Unable to find page.
get /v3/device-queries/{query_id}/
Retrieve a device query. Show more Show less
Retrieve a specific device query.
Path parameters
query_id (required)
Path Parameter
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "query" : "id=00000000000000000000000000000000",
  "name" : "00000000000000000000000000000000",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "00000000000000000000000000000000",
  "object" : "device-query"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Retrieved result successfully. DeviceQuery
400 Validation error: The data used to create the device query did not validate.
401 Not authenticated.
404 Unable to find device query.
put /v3/device-queries/{query_id}/
Update a device query Show more Show less
Update a specifc device query.
Path parameters
query_id (required)
Path Parameter
Request body
Body Parameter — Device query update object.
Return type
Example data
Content-Type: application/json
{
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "query" : "id=00000000000000000000000000000000",
  "name" : "00000000000000000000000000000000",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "00000000000000000000000000000000",
  "object" : "device-query"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Device updated. DeviceQuery
400 Validation error: The data used to update the device query did not validate.
401 Not authenticated.
404 Unable to update device query because it can't be found.
get /v3/devices/{id}/
Retrieve information about a specific device.
Path parameters
id (required)
Path Parameter
Return type
Example data
Content-Type: application/json
{
  "enrolment_list_timestamp" : "2017-05-22T12:37:55.576563Z",
  "description" : "description",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "device_execution_mode" : 0,
  "custom_attributes" : "{ 'key': 'value' }",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "auto_update" : true,
  "state" : "unenrolled",
  "id" : "00000000000000000000000000000000",
  "mechanism" : "connector",
  "deployment" : "",
  "device_key" : "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00",
  "mechanism_url" : "",
  "manifest" : "",
  "endpoint_name" : "00000000-0000-0000-0000-000000000000",
  "manifest_timestamp" : "2017-05-22T12:37:55.576563Z",
  "groups" : [ "00000000000000000000000000000000" ],
  "serial_number" : "00000000-0000-0000-0000-000000000000",
  "connector_expiration_date" : "2000-01-23",
  "endpoint_type" : "",
  "host_gateway" : "",
  "account_id" : "00000000000000000000000000000000",
  "bootstrapped_timestamp" : "2017-05-22T12:37:55.576563Z",
  "bootstrap_expiration_date" : "2000-01-23",
  "vendor_id" : "00000000-0000-0000-0000-000000000000",
  "firmware_checksum" : "0000000000000000000000000000000000000000000000000000000000000000",
  "name" : "00000000-0000-0000-0000-000000000000",
  "device_class" : "",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "ca_id" : "00000000000000000000000000000000",
  "deployed_state" : "development",
  "object" : "device"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Retrieved result successfully. DeviceData
400 Bad Request.
401 Not authenticated.
404 Unable to find device.
put /v3/devices/{id}/
Update a device Show more Show less
Update a specific device.
Path parameters
id (required)
Path Parameter — The ID of the device.
Request body
Device DeviceDataPutRequest (required)
Body Parameter
Return type
Example data
Content-Type: application/json
{
  "enrolment_list_timestamp" : "2017-05-22T12:37:55.576563Z",
  "description" : "description",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "device_execution_mode" : 0,
  "custom_attributes" : "{ 'key': 'value' }",
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "auto_update" : true,
  "state" : "unenrolled",
  "id" : "00000000000000000000000000000000",
  "mechanism" : "connector",
  "deployment" : "",
  "device_key" : "00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00",
  "mechanism_url" : "",
  "manifest" : "",
  "endpoint_name" : "00000000-0000-0000-0000-000000000000",
  "manifest_timestamp" : "2017-05-22T12:37:55.576563Z",
  "groups" : [ "00000000000000000000000000000000" ],
  "serial_number" : "00000000-0000-0000-0000-000000000000",
  "connector_expiration_date" : "2000-01-23",
  "endpoint_type" : "",
  "host_gateway" : "",
  "account_id" : "00000000000000000000000000000000",
  "bootstrapped_timestamp" : "2017-05-22T12:37:55.576563Z",
  "bootstrap_expiration_date" : "2000-01-23",
  "vendor_id" : "00000000-0000-0000-0000-000000000000",
  "firmware_checksum" : "0000000000000000000000000000000000000000000000000000000000000000",
  "name" : "00000000-0000-0000-0000-000000000000",
  "device_class" : "",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "ca_id" : "00000000000000000000000000000000",
  "deployed_state" : "development",
  "object" : "device"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Device updated. DeviceData
400 Validation error: The data used to update the device did not validate.
401 Not authenticated.
404 Unable to update device because it can't be found.
post /v3/device-groups/
Create a group.
Request body
group group (required)
Body Parameter — Group
Return type
Example data
Content-Type: application/json
{
  "devices_count" : 10,
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "name" : "My devices",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "Devices on the factory floor.",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "015c3029f6f7000000000001001000c3",
  "object" : "device-group",
  "custom_attributes" : {
    "key" : "value"
  }
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
201 Created. DeviceGroup
400 Bad Request. ErrorResponse
401 Unauthorized. ErrorResponse
409 Conflict - Group name already exists. ErrorResponse
delete /v3/device-groups/{device-group-id}/
Delete a group.
Path parameters
device-group-id (required)
Path Parameter — The ID of the group
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Success - group deleted.
401 Unauthorized. ErrorResponse
404 Not Found. ErrorResponse
get /v3/device-groups/
List all groups. Show more Show less
List all groups.
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
order (optional)
Query Parameter — The order of the records based on creation time, ASC or DESC; by default ASC.
after (optional)
Query Parameter — The ID of The item after which to retrieve the next page.
include (optional)
Query Parameter — Comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL encoded query string parameter to filter returned data.

Filtering

?filter={URL encoded query string}

The query string is made up of key/value pairs separated by ampersands. So for a query of

key1=value1&key2=value2&key3=value3 this would be encoded as follows: ?filter=key1%3Dvalue1%26key2%3Dvalue2%26key3%3Dvalue3

Filterable fields:

The table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
id  
devices_count
name  
custom_attributes  
created_at
updated_at
etag
 

The examples below show the queries in unencoded form.

By device group properties:

name__eq=mygroup

On date-time fields:

Date-time fields should be specified in UTC RFC3339 format YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds e.g. 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds e.g. 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened - without milliseconds and punctuation e.g. 20161130T162512Z

Date-time filtering supports three operators:

  • equality
  • greater than or equal to – field name suffixed with __gte
  • less than or equal to – field name suffixed with __lte

Lower and upper limits to a date-time range may be specified by including both the __gte and __lte forms in the filter. {field name}[|__lte|__gte]={UTC RFC3339 date-time}

By device group custom attributes:

custom_attributes__{param}={value} custom_attributes__tag=TAG1

Multi-field example

name__eq=mygroup&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Encoded:

?filter=name__eq%3Dmygroup%26created_at__gte%3D2016-11-30T16%3A25%3A12.1234Z%26created_at__lte%3D2016-12-30T00%3A00%3A00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated: name__in=group1,group2

Return type
Example data
Content-Type: application/json
{
  "data" : [ {
    "devices_count" : 10,
    "updated_at" : "2017-05-22T12:37:55.576563Z",
    "name" : "My devices",
    "created_at" : "2017-05-22T12:37:55.576563Z",
    "description" : "Devices on the factory floor.",
    "etag" : "2017-05-22T12:37:55.576563Z",
    "id" : "015c3029f6f7000000000001001000c3",
    "object" : "device-group",
    "custom_attributes" : {
      "key" : "value"
    }
  } ],
  "total_count" : 1,
  "limit" : 50,
  "after" : "01631667477600000000000100100374",
  "has_more" : false,
  "object" : "list",
  "order" : "DESC"
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. DeviceGroupPage
401 Unauthorized. ErrorResponse
404 Not Found. ErrorResponse
post /v3/device-groups/{device-group-id}/devices/add/
Add a device to a group Show more Show less
Add one device to a group.
Path parameters
device-group-id (required)
Path Parameter — The ID of the group.
Request body
body DeviceGroupManipulation (required)
Body Parameter — Body of the request.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Success - device added.
400 Bad Request. ErrorResponse
401 Unauthorized. ErrorResponse
404 Not found. ErrorResponse
post /v3/device-groups/{device-group-id}/devices/remove/
Remove a device from a group Show more Show less
Remove one device from a group.
Path parameters
device-group-id (required)
Path Parameter — The ID of the group.
Request body
body DeviceGroupManipulation (required)
Body Parameter — Body of the request.
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Success - device removed.
400 Bad Request. ErrorResponse
401 Unauthorized. ErrorResponse
404 Not Found. ErrorResponse
get /v3/device-groups/{device-group-id}/devices/
Get a page of devices Show more Show less
Get a page of devices.
Path parameters
device-group-id (required)
Path Parameter
Query parameters
limit (optional)
Query Parameter — How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
order (optional)
Query Parameter — The order of the records based on creation time, ASC or DESC; by default ASC.
after (optional)
Query Parameter — The ID of The item after which to retrieve the next page.
include (optional)
Query Parameter — Comma-separated list of data fields to return. Currently supported: total_count.
filter (optional)
Query Parameter

URL encoded query string parameter to filter returned data.

Filtering

?filter={URL encoded query string}

The query string is made up of key/value pairs separated by ampersands. So for a query of

key1=value1&key2=value2&key3=value3 this would be encoded as follows: ?filter=key1%3Dvalue1%26key2%3Dvalue2%26key3%3Dvalue3

Filterable fields:

The table lists all the fields that can be filtered on with certain filters:

Field = / __eq / __neq __in / __nin __lte / __gte
id  
devices_count
name  
description  
custom_attributes  
created_at
updated_at
etag
 

The examples below show the queries in unencoded form.

By device properties (all properties are filterable):

state=[unenrolled|cloud_enrolling|bootstrapped|registered] device_class={value}

On date-time fields:

Date-time fields should be specified in UTC RFC3339 format YYYY-MM-DDThh:mm:ss.msZ. There are three permitted variations:

  • UTC RFC3339 with milliseconds e.g. 2016-11-30T16:25:12.1234Z
  • UTC RFC3339 without milliseconds e.g. 2016-11-30T16:25:12Z
  • UTC RFC3339 shortened - without milliseconds and punctuation e.g. 20161130T162512Z

Date-time filtering supports three operators:

  • equality
  • greater than or equal to – field name suffixed with __gte
  • less than or equal to – field name suffixed with __lte

Lower and upper limits to a date-time range may be specified by including both the __gte and __lte forms in the filter. {field name}[|__lte|__gte]={UTC RFC3339 date-time}

On device custom attributes:

custom_attributes__{param}={value} custom_attributes__tag=TAG1

Multi-field example

state=bootstrapped&created_at__gte=2016-11-30T16:25:12.1234Z&created_at__lte=2016-12-30T00:00:00Z

Encoded:

?filter=state%3Dbootstrapped%26created_at__gte%3D2016-11-30T16%3A25%3A12.1234Z%26created_at__lte%3D2016-11-30T00%3A00%3A00Z

Filtering with filter operators

String field filtering supports the following operators:

  • equality: __eq
  • non-equality: __neq
  • in : __in
  • not in: __nin

For __in and __nin filters list of parameters must be comma-separated: state__nin=unenrolled,dergistered

Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
204 Ok.
400 Bad Request. ErrorResponse
401 Unauthorized. ErrorResponse
404 Not found. ErrorResponse
get /v3/device-groups/{device-group-id}/
Get a group.
Path parameters
device-group-id (required)
Path Parameter — The group ID
Return type
Example data
Content-Type: application/json
{
  "devices_count" : 10,
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "name" : "My devices",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "Devices on the factory floor.",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "015c3029f6f7000000000001001000c3",
  "object" : "device-group",
  "custom_attributes" : {
    "key" : "value"
  }
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. DeviceGroup
400 Bad request. ErrorResponse
401 Unauthorized. ErrorResponse
404 Not Found. ErrorResponse
put /v3/device-groups/{device-group-id}/
Modify the attributes of a group. Show more Show less
Modify the attributes of a group.
Path parameters
device-group-id (required)
Path Parameter
Request body
group group_1 (required)
Body Parameter — Group
Return type
Example data
Content-Type: application/json
{
  "devices_count" : 10,
  "updated_at" : "2017-05-22T12:37:55.576563Z",
  "name" : "My devices",
  "created_at" : "2017-05-22T12:37:55.576563Z",
  "description" : "Devices on the factory floor.",
  "etag" : "2017-05-22T12:37:55.576563Z",
  "id" : "015c3029f6f7000000000001001000c3",
  "object" : "device-group",
  "custom_attributes" : {
    "key" : "value"
  }
}
Produces
This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json
Responses
status description schema
200 Ok. DeviceGroup
400 Bad Request. ErrorResponse
401 Unauthorized. ErrorResponse
404 Not Found. ErrorResponse

Models

DeviceData

groups (optional)
array[String] An array containing an ID of each group this device belongs to.
enrolment_list_timestamp (optional)
Date The claim date/time. format: date-time
vendor_id (optional)
String The device vendor ID.
updated_at (optional)
Date The time the object was updated. format: date-time
state (optional)
String The current state of the device.
Enum:
unenrolled
cloud_enrolling
bootstrapped
registered
deregistered
serial_number (optional)
String The serial number of the device.
object (optional)
String The API resource entity.
name (optional)
String The name of the device.
mechanism_url (optional)
String The address of the connector to use.
mechanism (optional)
String The ID of the channel used to communicate with the device.
Enum:
connector
direct
manifest_timestamp (optional)
Date The timestamp of the current manifest version. format: date-time
manifest (optional)
String DEPRECATED: The URL for the current device manifest.
host_gateway (optional)
String The endpoint_name of the host gateway, if appropriate.
firmware_checksum (optional)
String The SHA256 checksum of the current firmware image.
etag (optional)
Date The entity instance signature. format: date-time
endpoint_type (optional)
String The endpoint type of the device. For example, the device is a gateway.
endpoint_name (optional)
String The endpoint name given to the device.
device_key (optional)
String The fingerprint of the device certificate.
id (optional)
String The ID of the device. The device ID is used across all Device Management APIs.
device_class (optional)
String An ID representing the model and hardware revision of the device.
description (optional)
String The description of the device.
deployment (optional)
String DEPRECATED: The last deployment used on the device.
deployed_state (optional)
String DEPRECATED: The state of the device's deployment.
Enum:
development
production
custom_attributes (optional)
map[String, String] Up to five custom key-value attributes.
created_at (optional)
Date The timestamp of when the device was created in the device directory. format: date-time
connector_expiration_date (optional)
date The expiration date of the certificate used to connect to LwM2M server. format: date
ca_id (optional)
String The certificate issuer's ID.
bootstrapped_timestamp (optional)
Date The timestamp of the device's most recent bootstrap process. format: date-time
bootstrap_expiration_date (optional)
date The expiration date of the certificate used to connect to bootstrap server. format: date
auto_update (optional)
Boolean DEPRECATED: Mark this device for automatic firmware update.
device_execution_mode (optional)
Integer

The execution mode from the certificate of the device. Defaults to inheriting from host_gateway device. Permitted values:

  • 0 - unspecified execution mode (default if host_gateway invalid or not set)
  • 1 - development devices
  • 5 - production devices
account_id (optional)
String The ID of the associated account.

DeviceDataPatchRequest

groups (optional)
array[String] An array containing an ID of each group this device belongs to.
object (optional)
String The API resource entity.
name (optional)
String The name of the device.
host_gateway (optional)
String The endpoint_name of the host gateway, if appropriate.
endpoint_type (optional)
String The endpoint type of the device. For example, the device is a gateway.
endpoint_name (optional)
String The endpoint name given to the device.
device_key (optional)
String The fingerprint of the device certificate.
description (optional)
String The description of the device.
custom_attributes (optional)
map[String, String] Up to five custom key-value attributes. Note that keys cannot start with a number. Both keys and values are limited to 128 characters.
ca_id (optional)
String The certificate issuer's ID.
auto_update (optional)
Boolean DEPRECATED: Mark this device for automatic firmware update.

DeviceDataPostRequest

groups (optional)
array[String] An array containing an ID of each group this device belongs to.
vendor_id (optional)
String The device vendor ID.
state (optional)
String The current state of the device.
Enum:
unenrolled
cloud_enrolling
bootstrapped
registered
deregistered
serial_number (optional)
String The serial number of the device.
object (optional)
String The API resource entity.
name (optional)
String The name of the device.
mechanism_url (optional)
String The address of the connector to use.
mechanism (optional)
String The ID of the channel used to communicate with the device.
Enum:
connector
direct
manifest (optional)
String DEPRECATED: The URL for the current device manifest.
host_gateway (optional)
String The endpoint_name of the host gateway, if appropriate.
firmware_checksum (optional)
String The SHA256 checksum of the current firmware image.
endpoint_type (optional)
String The endpoint type of the device. For example, the device is a gateway.
endpoint_name (optional)
String The endpoint name given to the device.
device_key (optional)
String The fingerprint of the device certificate.
device_class (optional)
String An ID representing the model and hardware revision of the device.
description (optional)
String The description of the device.
deployment (optional)
String DEPRECATED: The last deployment used on the device.
custom_attributes (optional)
map[String, String] Up to five custom key-value attributes. Note that keys cannot start with a number. Both keys and values are limited to 128 characters.
connector_expiration_date (optional)
Date The expiration date of the certificate used to connect to the LwM2M server. format: date-time
ca_id (optional)
String The certificate issuer's ID.
bootstrapped_timestamp (optional)
Date The timestamp of the device's most recent bootstrap process. format: date-time
bootstrap_expiration_date (optional)
Date The expiration date of the certificate used to connect to bootstrap server. format: date-time
auto_update (optional)
Boolean DEPRECATED: Mark this device for automatic firmware update.
device_execution_mode (optional)
Integer

The execution mode from the certificate of the device. Permitted values:

  • 0 - unspecified execution mode (default)
  • 1 - development devices
  • 5 - production devices

DeviceDataPutRequest

groups (optional)
array[String] An array containing an ID of each group this device belongs to.
object (optional)
String The API resource entity.
name (optional)
String The name of the device.
host_gateway (optional)
String The endpoint_name of the host gateway, if appropriate.
endpoint_type (optional)
String The endpoint type of the device. For example, the device is a gateway.
endpoint_name (optional)
String The endpoint name given to the device.
device_key (optional)
String The fingerprint of the device certificate.
description (optional)
String The description of the device.
custom_attributes (optional)
map[String, String] Up to five custom key-value attributes. Note that keys cannot start with a number. Both keys and values are limited to 128 characters.
ca_id (optional)
String The certificate issuer's ID.
auto_update (optional)
Boolean DEPRECATED: Mark this device for automatic firmware update.

DeviceEqNeqFilter

account_id (optional)
auto_update (optional)
bootstrap_expiration_date (optional)
Date format: date-time
bootstrapped_timestamp (optional)
Date format: date-time
ca_id (optional)
connector_expiration_date (optional)
Date format: date-time
created_at (optional)
Date format: date-time
custom_attributes (optional)
deployed_state (optional)
deployment (optional)
description (optional)
device_class (optional)
device_execution_mode (optional)
id (optional)
device_key (optional)
endpoint_name (optional)
endpoint_type (optional)
etag (optional)
Date format: date-time
firmware_checksum (optional)
host_gateway (optional)
manifest (optional)
manifest_timestamp (optional)
Date format: date-time
mechanism (optional)
mechanism_url (optional)
name (optional)
serial_number (optional)
state (optional)
updated_at (optional)
Date format: date-time
vendor_id (optional)
enrolment_list_timestamp (optional)
Date format: date-time

DeviceEventData

etag (optional)
Date format: date-time
created_at (optional)
Date format: date-time
object (optional)
String The API resource entity.
changes (optional)
data (optional)
map[String, String] Additional data relevant to the event.
date_time
Date format: date-time
description (optional)
id
device_id (optional)
event_type (optional)
String Event code
event_type_category (optional)
String Category code which groups the event type by a summary category.
event_type_description (optional)
String Generic description of the event
state_change (optional)

DeviceEventEqNeqFilter

date_time (optional)
Date format: date-time
description (optional)
id (optional)
device_id (optional)
event_type (optional)
state_change (optional)

DeviceEventGteLteFilter

date_time (optional)
Date format: date-time

DeviceEventInNinFilter

date_time (optional)
Date format: date-time
description (optional)
id (optional)
device_id (optional)
event_type (optional)
state_change (optional)

DeviceEventPage

after (optional)
data (optional)
has_more (optional)
limit (optional)
object (optional)
order (optional)
total_count (optional)

DeviceGroup

etag (optional)
Date format: date-time
updated_at (optional)
Date The time the object was updated. format: date-time
created_at (optional)
Date The time the campaign was created. format: date-time
object (optional)
String Entity name: always 'device-group'.
custom_attributes (optional)
description (optional)
String The description of the group.
name (optional)
String Name of the group.
devices_count (optional)
Integer The number of devices in this group.
id (optional)
String The group ID.

DeviceGroupManipulation

device_id (optional)

DeviceGroupPage

after (optional)
String An offset token for current page.
data (optional)
has_more (optional)
Boolean Are there more results available.
limit (optional)
Integer How many objects to retrieve in the page. The minimum limit is 2 and the maximum is 1000. Limit values outside of this range are set to the closest limit.
object (optional)
String The type of this API object is a "list".
order (optional)
String The creation time based order of the entries.
total_count (optional)
Integer format: integer

DeviceGteLteFilter

bootstrap_expiration_date (optional)
Date format: date-time
bootstrapped_timestamp (optional)
Date format: date-time
connector_expiration_date (optional)
Date format: date-time
created_at (optional)
Date format: date-time
etag (optional)
Date format: date-time
manifest_timestamp (optional)
Date format: date-time
updated_at (optional)
Date format: date-time
enrolment_list_timestamp (optional)
Date format: date-time

DeviceInNinFilter

account_id (optional)
auto_update (optional)
bootstrap_expiration_date (optional)
Date format: date-time
bootstrapped_timestamp (optional)
Date format: date-time
ca_id (optional)
connector_expiration_date (optional)
Date format: date-time
created_at (optional)
Date format: date-time
custom_attributes (optional)
deployed_state (optional)
deployment (optional)
description (optional)
device_class (optional)
device_execution_mode (optional)
id (optional)
device_key (optional)
endpoint_name (optional)
endpoint_type (optional)
etag (optional)
Date format: date-time
firmware_checksum (optional)
host_gateway (optional)
manifest (optional)
manifest_timestamp (optional)
Date format: date-time
mechanism (optional)
mechanism_url (optional)
name (optional)
serial_number (optional)
state (optional)
updated_at (optional)
Date format: date-time
vendor_id (optional)
enrolment_list_timestamp (optional)
Date format: date-time

DevicePage

after (optional)
data (optional)
has_more (optional)
limit (optional)
object (optional)
order (optional)
total_count (optional)

DeviceQuery

created_at
Date The timestamp of when the device was created in the device directory. format: date-time
etag
Date The entity instance signature. format: date-time
id
String The ID of the query.
name
String The name of the query.
object
String The API resource entity.
query
String The device query.
updated_at
Date The time the object was updated. format: date-time

DeviceQueryEqNeqFilter

created_at (optional)
Date format: date-time
etag (optional)
Date format: date-time
id (optional)
name (optional)
query (optional)
updated_at (optional)
Date format: date-time

DeviceQueryGteLteFilter

created_at (optional)
Date format: date-time
etag (optional)
Date format: date-time
updated_at (optional)
Date format: date-time

DeviceQueryInNinFilter

created_at (optional)
Date format: date-time
etag (optional)
Date format: date-time
id (optional)
name (optional)
query (optional)
updated_at (optional)
Date format: date-time

DeviceQueryPage

after (optional)
data
has_more
limit
Integer format: integer
object
order
total_count
Integer format: integer

DeviceQueryPatchRequest

name (optional)
String The name of the query.
query (optional)
String The device query.

DeviceQueryPostPutRequest

name
String The name of the query.
query
String The device query.

ErrorResponse

object (optional)
code (optional)
Integer Response code. format: int32
type (optional)
message (optional)
fields (optional)
request_id (optional)

ErrorResponse_fields

name (optional)
message (optional)

group

name (optional)
String Name of the group.
description (optional)
String The description of the group.
custom_attributes (optional)

group_1

custom_attributes (optional)
description (optional)
String The description of the group.
name (optional)
String Name of the group.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.