> This page is for Beam. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://mediakind.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server. # 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](ref:fleet-api#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` Reference: https://mediakind.ferndocs.com/beam/api/fleets/devices/list-devices ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### 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. The service returns the number of available items up to but not greater than the specified value `n`. - `$skiptoken` (string, optional) — Specifies a start offset to support paginated results. Use `@odata.nextLink` in the result object to enumerate the collection - it will be present only if there's more than one page of entities. - `$label_key` (string, optional) — Filters the set to the specified label key. If multiple $label_keys are specified, matching items must have all labels. - `$label` (string, optional) — Filters the set to the specified label key/value pair. Supports equality, inequality, and inexact matching. If multiple values are provided for the same key, items matching either value will be returned. ## Response ### 200 A list of devices - `supplemental` (ListResponseSupplementalSchema, required) — Supplemental info - `value` (list of DeviceGetSchema, required) — A list of devices. - `@odata.nextLink` (string, optional) — @odata.nextLink URL if the page length and number of items match. ## Errors ### 400 Bad Request Error Bad Request - `error` (ErrorDetail, required) — Pertinent information about the error - `ref` (string, required) — A reference to the request that caused the error. - `status` (integer, required) — The HTTP status code ### 401 Unauthorized Error Unauthorized - `error` (ErrorDetail, required) — Pertinent information about the error - `ref` (string, required) — A reference to the request that caused the error. - `status` (integer, required) — The HTTP status code ### 403 Forbidden Error Forbidden - `error` (ErrorDetail, required) — Pertinent information about the error - `ref` (string, required) — A reference to the request that caused the error. - `status` (integer, required) — The HTTP status code ### 404 Not Found Error Not Found - `error` (ErrorDetail, required) — Pertinent information about the error - `ref` (string, required) — A reference to the request that caused the error. - `status` (integer, required) — The HTTP status code ### 429 Too Many Requests Error Too Many Requests - `error` (ErrorDetail, required) — Pertinent information about the error - `ref` (string, required) — A reference to the request that caused the error. - `status` (integer, required) — The HTTP status code ### 500 Internal Server Error Internal Server Error - `error` (ErrorDetail, required) — Pertinent information about the error - `ref` (string, required) — A reference to the request that caused the error. - `status` (integer, required) — The HTTP status code ## Types ### ListResponseSupplementalSchema - `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` (PaginationInfoSchema, required) — Pagination info - `subscription` (ProjectInfoSchema, optional) — Project info ### DeviceGetSchema - `kind` (string, required) — The kind of record. - `metadata` (MetadataSchema, required) — Device metadata. - `spec` (DeviceBodySpec, required) — Device specification. - `status` (DeviceStatusGetSchema, required) — Device status. ### ErrorDetail - `code` (string, required) — The error code. - `detail` (string, required) — The error message. - `extraDetail` (map from string to any, optional) — Extra information regarding this error. ### PaginationInfoSchema - `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 ### ProjectInfoSchema - `id` (string, required) — Project ID - `name` (string, required) — Project name ### MetadataSchema - `id` (string, required) — The ID of the resource - `created` (datetime, optional) — The time when the resource was created - `createdBy` (string, optional) — 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 - `labels` (map from string to string, optional) — A dictionary of labels associated with the resource - `name` (string, optional) — The name of the resource - `updated` (datetime, optional) — The time when the resource was last updated - `updatedBy` (string, optional) — ID of the user who last updated the resource - `updatedByEmail` (string, optional) — Email of the user who last updated the resource ### DeviceBodySpec - `availableNetworks` (list of AvailableNetworkFragment, required) — The list of \<\>s available to the device and, optionally, the interfaces they are connected to. Leave the available networks list empty to give the device access to all of the networks with routes to the device's \<\>. Read [Available networks](ref:fleet-api#available-networks) to learn more. - `autoPreloadLatestSoftware` (boolean, optional, default: false) — Whether the device should automatically preload the latest available software version. - `desiredSoftwareVersion` (string, optional) — The desired version of software that should be running on the device. - `geolocation` (GeolocationFragment, optional) — Optional geolocation data for the device. - `locationId` (string, optional) — The location id is the identity of the actual device that will be associated with this record. This can be used instead of the `shortCode` field when registering an on-prem device. The location id does not change so this can be a simpler approach for large scale system administration. - `preloadSoftwareVersion` (string, optional) — A version of the software that should be preloaded on the device. - `shortCode` (string, optional) — The short code from a device's web user interface, used to on-board the device. The short code expires quickly, so it should be used immediately after it is generated. Read [On-board fleet devices](doc:on-board-fleet-devices) to learn more about on-boarding devices. - `siteName` (string, optional) — The name of the \<\> where the device is located. ### DeviceStatusGetSchema - `alarmSeverity` (enum, optional) — The most severe alarm level last reported by the device. - 0 - Clear - 1 - Info - 2 - Warning - 3 - Error - 4 - Critical - Allowed values: `0`, `1`, `2`, `3`, `4` - `assignedFlows` (list of AssignedFlowGetSchema, optional) — The a list of the \<\> names assigned to the device. - `beamHA` (BeamHASchema, optional) — Information about the beamHA the device is connected to. - `capabilities` (DeviceCapabilitiesSchema, optional) — Device capabilities based on software version and hardware. - `currentSoftwareVersion` (string, optional, nullable) — The current software version running on the device, as reported by the device. - `geolocation` (GeolocationFragment, optional) — Optional geolocation data for the device. - `interfaces` (list of DeviceInterfaceSchema, optional) — A list of the physical and virtual interfaces reported by the device. If an interface is referenced directly by a source or a destination, it may be continue to be present in the list even if the device no longer reports it. The `state` field indicates if the interface is currently present on the device. - `lastContact` (string, optional, nullable) — The last time the device contacted the system. - `locationId` (string, optional, nullable) — The location id is the identity of the actual device that will be associated with this record. This can be used instead of the `shortCode` field when registering an on-prem device. The location id does not change so this can be a simpler approach for large scale system administration. - `preloadedSoftware` (list of PreloadSoftwareInfo, optional, nullable) — The preloaded software present on the device. - `rollbackSoftwareVersion` (string, optional, nullable) — The rollback software version, as reported by the device. - `secondsSinceLastContact` (integer, optional, nullable) — The number of seconds since the last time the device contacted the system. - `serialNumber` (string, optional, nullable) — The serial number of the device, as reported by the device. - `softwareName` (string, optional, nullable) — The name of the software installed on the device. - `softwareUpgradeState` (enum, optional) — Indicates if a software upgrade is in progress or has failed. - Allowed values: `Idle`, `Switching`, `SwitchFailed` - `url` (string, optional) — The URL to access the device's web interface remotely. ### AvailableNetworkFragment - `interfaceName` (string, required) — The name of the \<\> that will be connected to the network. - `networkName` (string, required) — The name of the \<\> that will be made available to this device. ### GeolocationFragment - `coordinates` (list of double, required) — Co-ordinates that describe the geolocation (ISO 6709), an array of two floating point numbers [latitude(North - South), longitude(East - West)]. Set an empty array to clear the geolocation. ### AssignedFlowGetSchema - `name` (string, required) — The name of a \<\> assigned to the device. ### BeamHASchema - `roles` (list of string, required) — The roles of the device in the beamHA (high availability) group. - `activeControllerDeviceName` (string, optional) — The name of the active controller device in the beamHA. - `status` (string, optional) — The status of the beamHA group. Only returned for the active controller device. - `unregisteredDevices` (list of string, optional) — List of location IDs of devices that are part of the beamHA but not registered. Only returned for the active controller device. ### DeviceCapabilitiesSchema - `configurationBackup` (boolean, optional) — Whether the device supports configuration backup. Returns false for devices with beam software version older than 1.6. ### DeviceInterfaceSchema - `name` (string, required) — The name of the interface on the device. - `state` (enum, required) — Whether the interface is currently present on the device. If an interface is referenced directly by a source or a destination, it may be continue to be present in the list even if the device no longer reports it. - Allowed values: `NotPresent`, `Present` - `type` (enum, required) — The type of the physical or virtual interface on the device (IP, SDI/ASI or RF). - Allowed values: `IP`, `SDIASI`, `RF` - `ipAddresses` (list of string, optional) — The IP address associated with this interface, if applicable. ### PreloadSoftwareInfo - `name` (string, required) — The name of the preloaded software present on the device. - `state` (enum, required) — The current state of the preloaded software. - Allowed values: `Requested`, `Downloading`, `Downloaded`, `Importing`, `PreloadFailed`, `PreloadCancelled`, `Removing`, `Removed` - `version` (string, required) — The version of the preloaded software. - `downgradeCompatible` (boolean, optional) — Whether switching to this release is safe from an underlying component perspective. False if this release has a lower minimum version requirement than the currently installed release. True when no suitable reference release can be found (fail open). - `precentProgress` (integer, optional) — Indication of coarse progress for states with a significant duration. - `progressDetails` (string, optional, default: ) — Additional information about states with a significant duration. - `upgradeCompatible` (boolean, optional) — Whether the device's current software version meets the minimum version requirement for upgrading to this release. Mirrors the field on the device software list endpoint. ## Examples **Response** ```json { "supplemental": { "count": 1, "kind": "string", "operation": "string", "pagination": { "end": 1, "records": 1, "start": 1, "total": 1 }, "subscription": { "id": "string", "name": "string" } }, "value": [ { "kind": "string", "metadata": { "id": "string", "created": "2024-01-15T09:30:00Z", "createdBy": "string", "createdByEmail": "string", "displayName": "string", "labels": { "label1": "value1", "label2": "value2" }, "name": "string", "updated": "2024-01-15T09:30:00Z", "updatedBy": "string", "updatedByEmail": "string" }, "spec": { "availableNetworks": [ { "interfaceName": "eth0", "networkName": "internet" } ], "autoPreloadLatestSoftware": true, "desiredSoftwareVersion": "1.0.0.0", "geolocation": { "coordinates": [ 1.1 ] }, "locationId": "e188ca13-604f-4940-9afb-c3cb952baf01", "preloadSoftwareVersion": "1.0.0.1", "shortCode": "XU7U23WD", "siteName": "world" }, "status": { "alarmSeverity": 0, "assignedFlows": [ { "name": "channel-1" } ], "beamHA": { "roles": [ "Controller", "Worker", "Arbiter" ], "activeControllerDeviceName": "controller-01", "status": "OK", "unregisteredDevices": [ "e188ca13-604f-4940-9afb-c3cb952baf01" ] }, "capabilities": { "configurationBackup": true }, "currentSoftwareVersion": "1.0.0.2", "geolocation": { "coordinates": [ 1.1 ] }, "interfaces": [ { "name": "eth0", "state": "Present", "type": "IP", "ipAddresses": [ "10.10.10.1" ] } ], "lastContact": "string", "locationId": "e188ca13-604f-4940-9afb-c3cb952baf01", "preloadedSoftware": [ { "name": "beam", "state": "Downloading", "version": "1.0.0.0", "downgradeCompatible": true, "precentProgress": 25, "progressDetails": "1.2GiB of 4.9GiB", "upgradeCompatible": true } ], "rollbackSoftwareVersion": "1.0.0.1", "secondsSinceLastContact": 1, "serialNumber": "string", "softwareName": "beam", "softwareUpgradeState": "Idle", "url": "string" } } ], "@odata.nextLink": "string" } ``` **SDK Code** ```python import requests url = "https://app.mk.io/api/v1/projects/project_name/fleet/devices" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://app.mk.io/api/v1/projects/project_name/fleet/devices'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://app.mk.io/api/v1/projects/project_name/fleet/devices" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://app.mk.io/api/v1/projects/project_name/fleet/devices") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://app.mk.io/api/v1/projects/project_name/fleet/devices") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://app.mk.io/api/v1/projects/project_name/fleet/devices', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://app.mk.io/api/v1/projects/project_name/fleet/devices"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://app.mk.io/api/v1/projects/project_name/fleet/devices")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```