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

```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](/beam/api-guides/how-to/infrastructure/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:

<table>
  <thead>
    <tr>
      <th style="text-align: left">Field</th>
      <th style="text-align: left">Tells you</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left"><code>currentSoftwareVersion</code></td>
      <td style="text-align: left">The version running now.</td>
    </tr>
    <tr>
      <td style="text-align: left"><code>softwareUpgradeState</code></td>
      <td style="text-align: left"><code>Idle</code>, <code>Switching</code>, or <code>SwitchFailed</code> during a version change.</td>
    </tr>
    <tr>
      <td style="text-align: left"><code>alarmSeverity</code></td>
      <td style="text-align: left"><code>0</code> Clear, <code>1</code> Info, <code>2</code> Warning, <code>3</code> Error, <code>4</code> Critical.</td>
    </tr>
    <tr>
      <td style="text-align: left"><code>lastContact</code></td>
      <td style="text-align: left">When the device last reached the cloud.</td>
    </tr>
  </tbody>
</table>

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](/beam/api-guides/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](/beam/api-guides/how-to/fleets/backups-and-restores): protect device state before major changes.
- [Software and updates](/beam/api-guides/how-to/fleets/software-and-updates): control desired and preloaded software versions.