You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 2.3.

Device inventory

Overview

An API for device attribute management and device grouping. Intended for use by the web GUI.

Devices can upload vendor-specific attributes (software/hardware info, health checks, metrics, etc.) of various data types to the backend.

This API enables the user to:

  • list devices with their attributes
  • search devices by attribute value
  • use the results to create and manage device groups for the purpose of deployment scheduling

Version information

Version : 1

URI scheme

Host : hosted.mender.io
BasePath : /api/management/v1/inventory
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Paths


List devices inventories

GET /devices

Description

Returns a paged collection of devices and their attributes. Accepts optional search and sort parameters.

Searching Searching by attributes values is accomplished by appending attribute name/value pairs to the query string, e.g.: GET /devices?attr_name_1=foo&attr_name_2=100

Parameters

Type Name Description Schema Default
Query group
optional
Limits result to devices in the given group. string
Query has_group
optional
Limit result to devices assigned to a group. boolean
Query page
optional
Starting page. number (integer) 1
Query per_page
optional
Maximum number of results per page. number (integer) 10
Query sort
optional
Sort devices by attribute.
The parameter is formatted as a comma-separated list of attribute
names and sort order.

The order direction (ord) must be either asc or desc for
ascending and descending respectively.
Defaults to desc if not specified.

For example: ?sort=attr1:asc,attr2:desc
will sort by 'attr1' ascending, and then by 'attr2' descending.
string (attr[:ord][,attr[:ord]...])

Responses

HTTP Code Description Schema
200 Successful response.
Headers :
Link (string) : Standard page navigation header, supported relations: 'first', 'next', and 'prev'.
X-Total-Count (string) : Total number of devices found.
< DeviceInventory > array
400 Missing or malformed request parameters. Error
500 Internal error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
[ {
  "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
  "attributes" : [ {
    "name" : "ip_addr",
    "scope" : "inventory",
    "value" : "1.2.3.4",
    "description" : "IP address"
  }, {
    "name" : "mac_addr",
    "scope" : "inventory",
    "value" : "00.01:02:03:04:05",
    "description" : "MAC address"
  } ],
  "updated_ts" : "2016-10-03T16:58:51.639Z"
}, {
  "id" : "76f40e5956c699e327489213df4459d1923e1a806603def19d417d004a4a3ef",
  "attributes" : [ {
    "name" : "mac",
    "scope" : "inventory",
    "value" : "00:01:02:03:04:05",
    "description" : "MAC address"
  } ],
  "updated_ts" : "2016-10-04T18:24:21.432Z"
} ]
Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Get a selected device's inventory

GET /devices/{id}

Parameters

Type Name Description Schema
Path id
required
Device identifier. string

Responses

HTTP Code Description Schema
200 Successful response - the device was found. DeviceInventory
404 The device was not found. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
{
  "id" : "291ae0e5956c69c2267489213df4459d19ed48a806603def19d417d004a4b67e",
  "attributes" : [ {
    "name" : "ip_addr",
    "scope" : "inventory",
    "value" : "1.2.3.4",
    "description" : "IP address"
  }, {
    "name" : "mac_addr",
    "scope" : "inventory",
    "value" : "00.01:02:03:04:05",
    "description" : "MAC address"
  } ],
  "updated_ts" : "2016-10-03T16:58:51.639Z"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Remove selected device's inventory

DELETE /devices/{id}

Parameters

Type Name Description Schema
Path id
required
Device identifier. string

Responses

HTTP Code Description Schema
204 Device removed No Content
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Get a selected device's group

GET /devices/{id}/group

Parameters

Type Name Description Schema
Path id
required
Device identifier. string

Responses

HTTP Code Description Schema
200 Successful response. If the device is not assigned to any group, the 'group' field will be set to 'null'. Group
400 Missing or malformed request params or body. See the error message for details. No Content
404 The device was not found. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
{
  "group" : "staging"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Add a device to a group

PUT /devices/{id}/group

Description

Adds a device to a group.

Note that a given device can belong to at most one group. If a device already belongs to some group, it will be moved to the selected one.

Parameters

Type Name Description Schema
Path id
required
Device identifier. string
Body group
required
Group descriptor. Group

Responses

HTTP Code Description Schema
204 Success - the device was added to the group. No Content
400 Missing or malformed request params or body. See the error message for details. No Content
404 The device was not found. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP request

Request body
{
  "group" : "staging"
}

Example HTTP response

Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Remove a device from a group

DELETE /devices/{id}/group/{name}

Description

Removes the device with identifier 'id' from the group 'group'.

Parameters

Type Name Description Schema
Path id
required
Device identifier. string
Path name
required
Group name. string

Responses

HTTP Code Description Schema
204 The device was successfully removed from the group. No Content
404 The device was not found or doesn't belong to the group. Error
500 Internal error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

List all groups existing device groups

GET /groups

Responses

HTTP Code Description Schema
200 Successful response. < string > array
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
[ "staging", "testing", "production" ]
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

List the devices belonging to a given group

GET /groups/{name}/devices

Parameters

Type Name Description Schema Default
Path name
required
Group name. string
Query page
optional
Starting page. integer 1
Query per_page
optional
Maximum number of results per page. integer 10

Responses

HTTP Code Description Schema
200 Successful response
Headers :
Link (string) : Standard header, we support 'first', 'next', and 'prev'.
X-Total-Count (string) : Custom header indicating the total number of devices in the given group.
< string > array
400 Invalid request parameters. Error
404 The group was not found. Error
500 Internal server error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Clear devices' group

DELETE /groups/{name}/devices

Description

Removes a list of devices from their respective groups. This API provides a bulk alternative to DELETE /devices/{id}/group/{name} for managing device groups.

Parameters

Type Name Description Schema
Path name
required
Group name. string
Body DeviceIDs
required
JSON list of device IDs to append to the group. < string > array

Responses

HTTP Code Description Schema
200 Successful response Response 200
400 Invalid request schema. Error
404 The group was not found. Error
500 Internal server error. Error

Response 200

Name Description Schema
updated_count
required
Number of devices for which the group was cleared sucessfully. number

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
{
  "updated_count" : 2
}
Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Add devices to group

PATCH /groups/{name}/devices

Description

Appends the list of devices in the request body to the given group. For devices already present in the group the operation has no effect.

Parameters

Type Name Description Schema
Path name
required
Group name. string
Body DeviceIDs
required
JSON list of device IDs to append to the group. < string > array

Responses

HTTP Code Description Schema
200 Successful response Response 200
400 Invalid request schema. Error
404 The group was not found. Error
500 Internal server error. Error

Response 200

Name Description Schema
matched_count
required
Number of devices listed that matched a valid device id internally. number
updated_count
required
Number of devices listed that changed group. number

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
{
  "updated_count" : 2,
  "matched_count" : 3
}
Response 400
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 404
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}
Response 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Definitions

Attribute

Attribute descriptor.

Name Description Schema
description
optional
Attribute description. string
name
required
A human readable, unique attribute ID, e.g. 'device_type', 'ip_addr', 'cpu_load', etc. string
value
required
The current value of the attribute.

Attribute type is implicit, inferred from the JSON type.

Supported types: number, string, array of numbers, array of strings.
Mixed type arrays are not allowed.
string

DeviceInventory

Name Description Schema
attributes
optional
A list of attribute descriptors. < Attribute > array
id
optional
Mender-assigned unique device ID. string
updated_ts
optional
Timestamp of the most recent attribute update. string

Error

Error descriptor.

Name Description Schema
error
optional
Description of the error. string
request_id
optional
Request ID (same as in X-MEN-RequestID header). string

Group

Name Description Schema
group
required
Device group. string

Security

ManagementJWT

API token issued by User Authentication service. Format: 'Bearer [JWT]'

Type : apiKey
Name : Authorization
In : HEADER