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.

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.

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

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:

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.

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.

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.