> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediakind.ferndocs.com/platform/how-to/fleets/device-management/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server.

# Manage devices

Device management is where most Fleets API workflows begin. MK.IO Beam is an on-premises media processing appliance, and the Fleets API is the cloud control plane for it. You register a device into a project, give it a site and the networks it can use, then move into backup, software, or diagnostic operations. For the on-device onboarding steps that precede registration, see [Onboard a fleet device](/mkio/how-to/managing-edge-devices/on-board-fleet-devices/api-onboarding).

## Register a device

A device is created with `PUT`, using its name in the URL. You associate the physical appliance with this record using either a `shortCode` or a `locationId` read from the device web interface.

* Terminal window

```bash
curl -X PUT "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/devices/beam-encoder-01" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "displayName": "Beam Encoder 01",
      "labels": { "location": "studio-a", "role": "encoder" }
    },
    "spec": {
      "shortCode": "XU7U23WD",
      "siteName": "headquarters",
      "availableNetworks": []
    }
  }'

```

The fields that matter:

`shortCode`: the 8-character code from the device web interface. It rotates frequently, so use it promptly.

* `locationId`: a stable device identifier that does not rotate. Prefer it for scripted, large-scale onboarding.

* `siteName`: the site the device belongs to. See Set up networks and sites.

* `availableNetworks`: the networks the device may use. An empty array gives it access to every network with a route to its site.

After registration, the device web interface shows **Registered: Yes**.

## Read the device and its status

```bash
curl -X GET "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/devices/beam-encoder-01" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

The `status` block is where you watch the device’s health and software. The fields worth tracking:

| Field                    | Tells you                                                       |
| ------------------------ | --------------------------------------------------------------- |
| `currentSoftwareVersion` | The version running now.                                        |
| `softwareUpgradeState`   | `Idle`, `Switching`, or `SwitchFailed` during a version change. |
| `alarmSeverity`          | `0` Clear, `1` Info, `2` Warning, `3` Error, `4` Critical.      |
| `lastContact`            | When the device last reached the cloud.                         |

The list endpoint supports `$filter`, `$orderby`, `$top`, `$skiptoken`, and label queries, including sorting on `status/alarmSeverity` and `status/currentSoftwareVersion`.

## Update device settings

Use `PATCH` to change settings such as the site, networks, or software preferences:

```bash
curl -X PATCH "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/devices/beam-encoder-01" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "autoPreloadLatestSoftware": true } }'

```

The software-related fields (`desiredSoftwareVersion`, `preloadSoftwareVersion`, `autoPreloadLatestSoftware`) are covered in [Software and updates](/platform/how-to/fleets/software-and-updates).

## What goes wrong

* Registration fails because the short code expired. Short codes rotate. Keep the device interface open so it shows the current code, or register with the non-rotating `locationId` instead.

* Deleting a device returns `409 Conflict`. The device is still referenced, for example by an assigned flow. Clear the dependency, then retry the delete.

```bash
curl -X DELETE "https://app.mk.io/api/v1/projects/<PROJECT_NAME>/fleet/devices/beam-encoder-01" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

```

## What comes next

* Backups and restores: protect device state before major changes.

* Software and updates: control desired and preloaded software versions.