> 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.

# Get Device

GET https://app.mk.io/api/v1/projects/{project_name}/fleet/devices/{name}

Get a device by name. To learn more about devices, read [Device Concept](ref:fleet-api#device-concept).

RBAC Capability Required: `fleet.device.get`

Reference: https://mediakind.ferndocs.com/beam/api/fleets/devices/get-device

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `project_name` (string, required)
- `name` (string, required)

## Response

### 200

A single device

- `kind` (string, required) — The kind of record.
- `metadata` (MetadataSchema, required) — Device metadata.
- `spec` (DeviceBodySpec, required) — Device specification.
- `status` (DeviceStatusGetSchema, required) — Device status.

## 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

### 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 \<\<glossary:network>>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 \<\<glossary:site>>. 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 \<\<glossary:site>> 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 \<\<glossary:flow>> 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.

### 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.

### AvailableNetworkFragment

- `interfaceName` (string, required) — The name of the \<\<glossary:device interface>> that will be connected to the network.
- `networkName` (string, required) — The name of the \<\<glossary:network>> 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 \<\<glossary:flow>> 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
{
  "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"
  }
}
```

**SDK Code**

```python
import requests

url = "https://app.mk.io/api/v1/projects/project_name/fleet/devices/name"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://app.mk.io/api/v1/projects/project_name/fleet/devices/name';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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/name"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	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/name")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://app.mk.io/api/v1/projects/project_name/fleet/devices/name")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.mk.io/api/v1/projects/project_name/fleet/devices/name', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://app.mk.io/api/v1/projects/project_name/fleet/devices/name");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://app.mk.io/api/v1/projects/project_name/fleet/devices/name")! 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()
```