List Devices

Get https://app.mk.io/api/v1/projects/:project_name/fleet/devices

List devices on the specified project. To learn more about devices, read Device Concept.

Listing, Sorting and Filtering Devices

This endpoint returns the list of devices in the specified project.

Sorting

The results from this endpoint can be ordered using the $orderby query parameter. Specify a list of field names, separated by commas where each one can optionally specify asc or desc.

Sorting is valid on the following fields: created, createdBy, displayName, id, labels, metadata/created, metadata/displayName, metadata/name, name, status/alarmSeverity, status/beamHA/activeControllerDeviceName, status/beamHA/roles, status/currentSoftwareVersion, status/lastContact, status/model, status/rollbackSoftwareVersion, status/serialNumber, updated, updatedBy

Filtering

There are two ways to filter the set of returned devices from this endpoint - the first is to use the $filter query parameter, the second is to use the $label_key and $label query parameters.

The $filter query parameter allows for devices to be filtered on the basis of fields in the schema using OData query syntax. See this document for more details on the syntax used.

Filters are valid on the following fields: created, createdBy, createdByEmail, createdByName, displayName, id, labels, metadata/created, metadata/displayName, metadata/name, name, spec/siteName, status/alarmSeverity, status/beamHA/activeControllerDeviceName, status/beamHA/roles, status/currentSoftwareVersion, status/lastContact, status/model, status/rollbackSoftwareVersion, status/serialNumber, updated, updatedBy, updatedByEmail, updatedByName

$label_key and $label are specific to querying devices based on their labels. Labels are a set of key-value pairs that can be used to identify devices with any arbitrary metadata you want, specifically for the purpose of retrieving relevant subsets of devices.

Examples:

?$top=10 - Returns only the first 10 devices from the list.

?$orderby=name desc - Sorts devices by name in descending order.

?$filter=name eq 'descriptive name' - Returns devices that match the provided name.

?$orderby=created desc - Sorts devices by creation date in descending order.

?$filter=created ge 2021-01-01T00:00:00Z - Returns devices created after January 1, 2021.

?$label=studio=paravalley - Returns devices with the label studio set to paravalley.

?$label=release-date~2023 - Returns devices with the label release-date set to a value that contains 2023.

?$label_key=studio&label_key=release-date - Returns devices with any value set for the studio label and the release-date label.

RBAC Capability Required: fleet.device.get

Authentication

Authorization Bearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

project_name string Required

Query parameters

$orderby string Optional

Specifies the key by which the result collection should be ordered.

$filter string Optional

Restricts the set of items returned.

$top string Optional

Specifies a non-negative integer n that limits the number of items returned from a collection.

$skiptoken string Optional

Specifies a start offset to support paginated results.

$label_key string Optional

Filters the set to the specified label key.

$label string Optional

Filters the set to the specified label key/value pair.

Response

200 A list of devices

@odata.nextLink string Optional

@odata.nextLink URL if the page length and number of items match.

supplemental object ListResponseSupplementalSchema Required

Supplemental info

count integer Required

Number of items returned

kind string Required

Type of items in the list

operation string Required

Operation type. Should always say 'list'

pagination object PaginationInfoSchema Required

Pagination info

end integer Required

Position of the last item in the list

records integer Required

Total number of items returned in the list

start integer Required

Position of the first item in the list

total integer Required

Total number of items in the project

subscription object ProjectInfoSchema Optional

Project info

id string Required

Project ID

name string Required

Project name

value list of objects DeviceGetSchema Required

A list of devices.

kind string Required

The kind of record.

metadata object MetadataSchema Required

Device metadata.

created string Optional format: date-time

The time when the resource was created

createdBy string Optional format: uuid

ID of the user who created the resource

createdByEmail string Optional

Email of the user who created the resource

displayName string Optional

The display name of the resource

id string Required format: uuid

The ID of the resource

labels map from strings to string Optional

A dictionary of labels associated with the resource

name string Optional

The name of the resource

updated string Optional format: date-time

The time when the resource was last updated

updatedBy string Optional format: uuid

ID of the user who last updated the resource

updatedByEmail string Optional

Email of the user who last updated the resource

spec object DeviceBodySpec Required

Device specification.

autoPreloadLatestSoftware boolean Optional Defaults to false

Whether the device should automatically preload the latest available software version.

availableNetworks list of objects AvailableNetworkFragment Required

The list of networks available to the device.

interfaceName string Required pattern: [^\s/]{1,16}

The name of the device interface that will be connected to the network.

networkName string Required pattern: ^a-z0-9?$

The name of the network that will be made available to this device.

desiredSoftwareVersion string Optional <=255 characters

The desired version of software that should be running on the device.

geolocation object GeolocationFragment Optional

Optional geolocation data for the device.

coordinates list of doubles Required 0-2 items

Co-ordinates that describe the geolocation (ISO 6709).

locationId string Optional pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

The location id.

preloadSoftwareVersion string Optional <=255 characters

A version of the software that should be preloaded on the device.

shortCode string Optional 8-8 characters

The short code from a device's web user interface.

siteName string Optional pattern: ^(a-z0-9?)?$

The name of the site where the device is located.

status object DeviceStatusGetSchema Required

Device status.

alarmSeverity enum Optional

The most severe alarm level last reported by the device.

assignedFlows list of objects AssignedFlowGetSchema Optional

The list of the flow names assigned to the device.

beamHA object BeamHASchema Optional

Information about the beamHA the device is connected to.

capabilities object DeviceCapabilitiesSchema Optional

Device capabilities based on software version and hardware.

currentSoftwareVersion string or null Optional <=255 characters

The current software version running on the device.

lastContact string or null Optional

The last time the device contacted the system.

serialNumber string or null Optional 1-255 characters

The serial number of the device.

url string Optional 1-2048 characters

The URL to access the device's web interface remotely.

Errors

400 Bad Request

error object ErrorDetail Required

Pertinent information about the error.

401 Unauthorized

error object ErrorDetail Required

Pertinent information about the error.