channels.md
Build with the Channels API
The Channels API is the local API of an MK.IO Beam device. It presents everything the device is doing as a number of channels, where one channel can cover the input, the processing, and the output of a single service. It is the API behind the Beam Essentials UI, and it runs on the device itself rather than in the MK.IO cloud.
Warning: The Channels API requires an MK.IO Beam device running version
1.12.0or higher. It is delivered as part of the Beam Essentials UI release, so devices on earlier versions do not serve these endpoints.
API overview
| Detail | Value |
|---|---|
| Base path | <DEVICE_ADDRESS>/ui/connectors/channels-api/latest |
| Scope | A single Beam device |
| Authentication | None beyond network access to the device |
| Reference | Channels API reference |
The base URL is the device itself, not api.mk.io. Every other MK.IO API is project-scoped and bearer authenticated, so if you already integrate with the Media or Fleets API, treat this as a separate integration. See Connect to a Beam device for how to build the address and connect to your Beam device.
How the main resources connect
The API exposes a handful of resource types, and channels are the centre of all of them:
- A channel holds a
spec(the configuration you send) and astatus(what the device reports back). - Interfaces are the physical and network ports available on the device. You read them to fill in the
interfaceandurlfields of a channel. - Channel alarms are the active faults raised against a named channel.
- Metrics and system information describe the device rather than any one channel.
A typical integration reads the interfaces once, creates channels against them, then polls channel status and alarms to drive a dashboard or an alerting rule.
Common workflow patterns
Automate a Beam device
- Connect and confirm the version
- Read the available interfaces
- Create and start a channel
- Poll status, health, and alarms
Guides
- How Beam channels work: Channel types, the split between spec and status, and how configuration is applied asynchronously.
- Connect to a Beam device: Build the base URL, use the Swagger page served by the device, and understand the current authentication model.
- Create and manage channels: A complete worked request, the input and output types each channel type accepts, and how to start, rename, and delete.
- Monitor channels and devices: Filter the channel list, read health and alarms, fetch thumbnails, and query device metrics.
- Import and export channels: Move a channel configuration between devices, or restore one after a rebuild.
Where to go deeper
- Beam Essentials UI covers the same channels through the device interface, including the creation wizard.
- Channels API reference is the complete field-level truth for every schema referenced in these guides.