# 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](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview#filter) 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](https://docs.mediakind.com/api-reference/fleets-api/schemas/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](https://docs.mediakind.com/api-reference/fleets-api/schemas/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](https://docs.mediakind.com/api-reference/fleets-api/schemas/projectinfoschema) Optional

Project info

id string Required

Project ID

name string Required

Project name

value list of objects [DeviceGetSchema](https://docs.mediakind.com/api-reference/fleets-api/schemas/devicegetschema) Required

A list of devices.

kind string Required

The kind of record.

metadata object [MetadataSchema](https://docs.mediakind.com/api-reference/fleets-api/schemas/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](https://docs.mediakind.com/api-reference/fleets-api/schemas/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](https://docs.mediakind.com/api-reference/fleets-api/schemas/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]([a-z0-9-]{0,61}[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](https://docs.mediakind.com/api-reference/fleets-api/schemas/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]([a-z0-9-]{0,61}[a-z0-9])?)?$

The name of the site where the device is located.

status object [DeviceStatusGetSchema](https://docs.mediakind.com/api-reference/fleets-api/schemas/devicestatusgetschema) Required

Device status.

alarmSeverity enum Optional

The most severe alarm level last reported by the device.

assignedFlows list of objects [AssignedFlowGetSchema](https://docs.mediakind.com/api-reference/fleets-api/schemas/assignedflowgetschema) Optional

The list of the flow names assigned to the device.

beamHA object [BeamHASchema](https://docs.mediakind.com/api-reference/fleets-api/schemas/beamhaschema) Optional

Information about the beamHA the device is connected to.

capabilities object [DeviceCapabilitiesSchema](https://docs.mediakind.com/api-reference/fleets-api/schemas/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](https://docs.mediakind.com/api-reference/fleets-api/schemas/errordetail) Required

Pertinent information about the error.

401 Unauthorized

error object [ErrorDetail](https://docs.mediakind.com/api-reference/fleets-api/schemas/errordetail) Required

Pertinent information about the error.