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:

  • manage filters (list, create, read, delete)
  • 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


Create a new saved filter from a filter definition

POST /filters

Parameters

Type Name Description Schema
Body body
optional
The definition of the filter body

body

Name Description Schema
name
optional
Name of the filter, must be unique. string
terms
optional
List of filter predicates, chained with boolean AND operators to build the search condition definition. < FilterPredicate > array

Responses

HTTP Code Description Schema
201 The filter was successfully created.
Headers :
Location (string) : URL of the newly created filter.
No Content
400 Missing or malformed request parameters. See error for details. Error
409 A filter with the same name already exists. Error
500 Internal error. Error

Consumes

  • application/json

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 409
{
  "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 the saved filters

GET /filters

Parameters

Type Name Description Schema Default
Query page
optional
Starting page. number (integer) 1
Query per_page
optional
Number of results per page. number (integer) 20

Responses

HTTP Code Description Schema
200 Successful response.
Headers :
Link (string) : Standard header, used for page navigation.

Supported relation types are 'first', 'next' and 'prev'.
X-Total-Count (string) : Custom header indicating the total number of saved filters for the given query parameters.
< Filter > array
400 Missing or malformed request parameters. See error for details. Error
500 Internal 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 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

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 criteria < SortCriteria > array

Responses

HTTP Code Description Schema
200 Successful response.
Headers :
X-Total-Count (string) : Custom header indicating the total number of devices for the given query parameters.
< DeviceInventory > array
400 Missing or malformed request parameters. See error for details. 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" : "identity",
    "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 the definition of a saved filter

GET /filters/{id}

Parameters

Type Name Description Schema
Path id
required
Filter identifier. string

Responses

HTTP Code Description Schema
200 Successful response. Filter
404 The filter was not found. ErrorNotFound
500 Internal error. Error

Tags

  • Management API

Security

Type Name
apiKey ManagementJWT

Example HTTP response

Response 200
{
  "id" : "myfilter",
  "name" : "My Filter",
  "terms" : [ {
    "scope" : "inventory",
    "attribute" : "serial_no",
    "type" : "$eq",
    "value" : "123456789"
  } ]
}
Response 404
{
  "error" : "filter not found",
  "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"
}

Delete a saved filter

DELETE /filters/{id}

Parameters

Type Name Description Schema
Path id
required
Filter identifier. string

Responses

HTTP Code Description Schema
204 The filter was successfully deleted. No Content
400 Missing or malformed request parameters. See error for details. Error
500 Internal error. Error

Consumes

  • application/json

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 500
{
  "error" : "failed to decode device group data: JSON payload is empty",
  "request_id" : "f7881e82-0492-49fb-b459-795654e7188a"
}

Search devices using saved filter

GET /filters/{id}/search

Parameters

Type Name Description Schema Default
Path id
required
Filter identifier. string
Query page
optional
Starting page. number (integer) 1
Query per_page
optional
Number of results per page. number (integer) 20

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
404 The filter was not found. ErrorNotFound
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 404
{
  "error" : "filter not found",
  "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

ErrorNotFound

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

Filter

Filter definition

Name Description Schema
id
required
Unique identifier of the saved filter. string
name
required
Name of the saved filter. string
terms
optional
< FilterPredicate > array

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.

| Operator | Name | Argument type |
|:----------:|:-----------------------------|:----------------|
| $eq | Equal (==) | any |
| $ne | Not equal (!=) | any |
| $gt | Greater than (>) | any |
| $gte | Greater than or equal (>=) | any |
| $lt | Less than (<) | any |
| $lte | Less than or equal (<=) | any |
| $exists | Attribute exists | bool |
| $in | Is an element of | array |
| $nin | Is not an element of | array |
| $regex | Regex filter | string |
enum ($eq, $gt, $gte, $in, $lt, $lte, $ne, $nin, $exists, $regex)
value
required
The value of the attribute to be used in filtering.
Attribute type is implicit, inferred from the JSON type.

The $exists operator expects a boolean value: true means the specified
attribute exists, false means the specified attribute doesn't exist.

The $regex operator expects a string as a Perl compatible regular expression
(PCRE), automatically anchored by ^. If the regular expression is not valid,
the filter will produce no results. If you need to specify options and flags,
you can provide the full regex in the format of /regex/flags, for example
/[a-z]+/i.
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