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

Device inventory filters and search

Overview

An API for inventory-based filters management and device search. It is 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 as scoped attributes.

This API enables the user to:

  • search devices by inventory scoped attribute value
  • use the results to create and manage device groups for deployment scheduling

Version information

Version : 2

URI scheme

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

Consumes

  • application/json

Produces

  • application/json

Paths


Search devices based on inventory attributes

POST /filters/search

Description

Returns a paged collection of devices and their attributes.

If multiple filter predicates are specified, the filters are combined using boolean and operator.

Parameters

Type Name Description Schema
Body body
optional
The search and sort parameters of the filter body

body

Name Description Schema
filters
optional
List of filter predicates. < FilterPredicate > array
page
optional
Starting page. number (integer)
per_page
optional
Maximum number of results per page. number (integer)
sort
optional
List of ordered sort criterias < SortCriteria > array

Responses

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

Consumes

  • application/json

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"
}

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
scope
required
The scope of the attribute.

Scope is a string and acts as namespace for the attribute name.
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 arrays are not allowed.
string

DeviceInventory

Name Description Schema
attributes
optional
A list of attribute descriptors. < Attribute > array
id
optional
Mender-assigned unique 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

FilterPredicate

Attribute filter predicate

Name Description Schema
attribute
required
Attribute name. string
scope
required
Attribute scope. string
type
required
Type or operator of the filter predicate. enum ($eq)
value
optional
The value of the attribute to be used in filtering.
Attribute type is implicit, inferred from the JSON type.
string

SortCriteria

Sort criteria definition

Name Description Schema
attribute
required
Attribute name. string
order
required
Order direction, ascending ("asc") or descending ("desc"). enum (asc, desc)
scope
required
Attribute scope. string

Security

ManagementJWT

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

Type : apiKey
Name : Authorization
In : HEADER