Connect to a Beam device

The Channels API is served by the Beam device, so there is no central endpoint and no token exchange. You address the device directly, on the same host and port you already use to reach its web interface.

Build the base URL

Take the address you use for the device web interface and append the API path:

<DEVICE_ADDRESS>/ui/connectors/channels-api/latest

<DEVICE_ADDRESS> is the scheme, host, and port of the device, for example http://10.0.0.10:8080. Whether you need a port, and which one, depends on how the device is deployed and secured. Connect to the Controller lists the access URL forms, including the ports used for containerized solutions and for HTTPS.

A full request URL therefore looks like this:

curl http://10.0.0.10:8080/ui/connectors/channels-api/latest/channels/

Try it on the device first

The device serves an interactive Swagger page for its own build of the API. Open it in a browser at:

<DEVICE_ADDRESS>/ui/connectors/channels-api/latest/docs/

This is the fastest way to see the endpoints, and you can execute requests against the device from the page itself. Use it to confirm connectivity before you write any integration code. The Channels API reference documents the same API on this site, so use whichever suits you.

Authentication

There is currently no authentication on the Channels API beyond network access to the device. Any client that can reach the device address can read and change its channels.

Treat network access as the only control you have. Keep Beam devices on a management network that is not reachable from untrusted clients, and do not expose the device address publicly.

Confirm the device version

The API is only present on Beam 1.12.0 and higher. Requests to a device on an earlier version do not reach the API at all, so a connection error or a 404 on the base path is the expected symptom rather than an authentication failure.

Check the version the device reports:

curl <DEVICE_ADDRESS>/ui/connectors/channels-api/latest/system/

The response wraps the device identity in a data object:

{
  "data": {
    "softwareVersion": "1.12.0.7",
    "softwareName": "beam",
    "serialNumber": "",
    "hardwareModel": "VEGA-7010"
  }
}

softwareVersion carries a build number as a fourth component, so compare it part by part rather than against the string 1.12.0. A device that does not report a value returns an empty string, as serialNumber does above, so check for emptiness rather than for null.

A successful response here also confirms your base URL is correct, which makes it a useful first call.

Check that the device can be managed

A device may be on a supported version but still be running channels that predate the Channels API. GET /deployment/eligibility/ reports whether the API can take over the device:

curl <DEVICE_ADDRESS>/ui/connectors/channels-api/latest/deployment/eligibility/

canRun is the verdict. deploymentState describes the current state of the device, and resources lists the existing services, feeds, and saved configurations found on it. Each entry carries canUpgrade and a reason, so when canRun is false the resources list tells you which object is blocking it.

Reach a device you cannot route to

If the device is registered in MK.IO, you can open its interface remotely rather than connecting over the local network. See Access the remote device UI.

Next step

With a base URL that returns a system response, you can create your first channel. See Create and manage channels.