Device API

The device API lets dashboards, the assistant, and integrations call a connected device’s own HTTP API without opening its web interface. Overvis defines, for each supported device model, which operations HMI may call, which workspace role each one needs, and where it may be used. Only those operations can be called; there is no way to send another method or path. HMI reaches the device over its VPN connection and sends no credentials.

Device API operations are available for PIN endpoints whose registry SKU a built-in manifest lists: MC252 (mc252) and MC261L (mc261, mc261l). Direct and WireGuard endpoints, disabled endpoints, and other devices are refused.

List operations

device.api.list returns the manifest and model of the endpoint’s device and the operations the caller’s workspace role and current calling surface allow. Each operation has its effect (read or write, see Effect), its minimum role, and keyRoles: input keys that need a stronger role when they are sent (Roles). Operation names and descriptions are in English.

{ "endpointId": "$endpointId" }

{
  "manifestId": "overvis/mc252",
  "model": "mc252",
  "operations": [
    {
      "id": "modbus.read",
      "name": "Modbus read request",
      "description": "Queues a Modbus read and returns its transaction id as tid; …",
      "effect": "read",
      "minRole": "operator",
      "keyRoles": {}
    }
  ]
}

Effect

read means the operation only returns data and changes nothing the device or the equipment behind it stores or does. A read may reach downstream equipment to fetch data, for example a Modbus read request. Every other operation is a write, including commands, setting changes, writes to downstream equipment, and requests that make the device contact a server. The HTTP method does not decide the effect: a GET that switches an output is a write.

Describe an operation

device.api.describe returns one listed operation with its HTTP method, the JSON Schemas of its query and body input, its timeout, its rate limit, and surfaces: the manifest’s allowed calling surfaces (dashboards, assistant, or automations, meaning server automations). Use surfaces to check whether an operation available to the assistant is also allowed from a dashboard. The full manifest array is returned, not just the current surface. This is permission metadata, not a guarantee that a runtime supports that surface or a call will succeed: role, per-key role, input, endpoint, and runtime checks still apply. Both list and describe expose only operations allowed for the caller’s role and current surface.

{ "endpointId": "$endpointId", "operation": "modbus.response" }

Invoke an operation

device.api.invoke calls one operation and returns the device’s JSON answer as response. input has the query and body the operation describes; omit a part the operation does not take.

{
  "endpointId": "$endpointId",
  "operation": "modbus.read",
  "input": { "body": { "reqData": "010300000002" } }
}

{ "response": { "tid": 12 } }

A query value true sends a bare key (?ethernet&vpn) and false leaves the key out. Members the operation redacts, such as passwords and PIN codes, are removed from response.

Checks run in this order, and nothing reaches the device until all of them pass:

1. The caller can read the endpoint’s workspace, and the endpoint is an enabled PIN endpoint of a known device.
2. The device’s model has the operation. The assistant’s dashboard previews may call only read operations; a write is refused with push_agent_key.
3. The caller’s role meets the operation’s minimum role, raised by the role of each input key it sends.
4. The input matches the operation’s schemas. A body is at most 4 KB of JSON.
5. The operation may be used from where the call comes from. Assistant calls are assistant; every other API call is dashboards.
6. The operation’s rate limit has room. Limits count per endpoint and operation, across all callers.

Calls to one device run one at a time. Every call that passes these checks is recorded in activity history with its operation, input, and outcome. Input members that any operation of the manifest redacts are left out of that record.

Modbus requests

On an MC252 or MC261L, modbus.read and modbus.write queue a request and return its tid. modbus.response with that tid returns status BUSY until the answer is ready, then DONE. The device keeps only the last 20 answers. Any operator, editor, admin, or owner of the workspace may read an answer by its tid, whoever queued the request.

Roles and the assistant

Viewers can list operations but have none. Operators, editors, admins, and owners get the operations whose minimum role they meet. One device endpoint often does several things depending on the keys a request sends, so an operation can raise the role for individual input keys (keyRoles): a call needs the strongest role among the operation’s minimum role and the roles of the keys it sends. For example, an editor may change an MC252’s saved settings, while changing its network settings in the same call needs an admin. When the assistant invokes a write that needs an editor, admin or owner, the user confirms it first, unless they allowed device writes without asking. Reads and operator operations run without confirmation.

Dashboards call operations with the device API hooks.

Errors

Code	Meaning
device_api_endpoint_unsupported	The endpoint is not a PIN endpoint.
device_api_endpoint_disabled	The endpoint is disabled.
device_api_device_unsupported	No manifest lists the endpoint’s SKU.
device_api_operation_not_found	The model has no such operation, or the caller may not see it. details.id names it.
device_api_role_too_low	details.requiredRole is the role the call needs.
device_api_surface_not_allowed	The operation may not be used from details.surface.
device_api_input_invalid	details.part is query or body; details.issues lists the schema failures.
device_api_rate_limited	details.retryAfterMs is when the next call fits the limit.
device_api_rate_limit_unavailable	Rate limiting is temporarily unavailable; nothing was sent. Retry later.
device_api_device_busy	Another request held the device longer than a call waits.
device_api_device_offline	The device did not answer over the VPN in time, or has no VPN address.
device_api_access_denied	The device answered 404 to a known operation: it grants the VPN session too little access.
device_api_device_error	The device answered with another error status (details.status) or with invalid JSON.

An MC252 answers 404, not 401 or 403, to a request its access level does not allow, so device_api_access_denied usually means the device’s own access settings limit the VPN session.