Endpoint procedures

endpoint.create takes no TCP settings: the server sets the defaults. Input schemas are closed, so a body with a field its kind does not have fails with input_invalid. Endpoint kinds, field rules, and defaults are in the endpoints reference. Steps for the Setup pages are in Configure endpoints.

Direct host

{
  "workspaceId": "$workspaceId",
  "kind": "direct",
  "name": "PLC",
  "hostname": "plc.example.com"
}

The Overvis server opens the connection, so hostname is a name or address that the server reaches. Overvis VPN addresses and blocked private and loopback addresses are refused. Optional port defaults to 502. A successful create means the configuration was accepted, not that the device is connected; connection status comes from endpoint.status.

MC252 PIN

{
  "workspaceId": "$workspaceId",
  "kind": "pin",
  "name": "MC252",
  "pinCode": "ABCD1234"
}

pinCode is the device’s 8-character alphanumeric pairing code; the server upper-cases it. A PIN body has no hostname or port: a PIN endpoint always uses port 502. An MC252 can be connected only once per workspace (endpoint_already_connected).

MC252 presence confirmation

Creating an MC252 PIN endpoint, and endpoint.disconnectOtherWorkspaces, need proof that someone is at the device: a press of its R button, or the 8-digit code from its screen.

Procedure	Input	Result
endpoint.beginPinPresence	workspaceId, pinCode, endpointId?	{ presenceRequired: false } for other SKUs, or { presenceRequired: true, challengeId, expiresAt, codeDisplayed }
endpoint.pollPinPresence	challengeId	pressed: true once the device saw a press after the challenge started; does not use up the challenge
endpoint.cancelPinPresence	challengeId	{ cancelled: true }; clears a displayed code from the device

codeDisplayed is true when the device screen shows a code. The code itself is never returned. endpointId is passed only for endpoint.disconnectOtherWorkspaces. The create body then also carries challengeId, sent before expiresAt, and authorizationCode only for a typed code:

{
  "workspaceId": "$workspaceId",
  "kind": "pin",
  "name": "MC252",
  "pinCode": "ABCD1234",
  "challengeId": "$challengeId",
  "authorizationCode": 12345678
}

Error	Meaning
endpoint_presence_required	The create body had no challengeId
endpoint_presence_not_pressed	No authorizationCode, and the device saw no press after the challenge started; the same challenge can be retried
endpoint_presence_rejected	The device did not confirm the typed code: it is wrong or no longer on the screen; the same challenge can be retried
endpoint_presence_invalid	Five wrong codes, or the challenge expired; a new endpoint.beginPinPresence is needed
endpoint_presence_unsupported	The MC252 firmware is older than 49 and cannot confirm presence
endpoint_presence_unavailable	The device could not be reached or did not answer as expected

To create an MC252 PIN endpoint:

1. Call endpoint.beginPinPresence with the workspace and the PIN.
2. If the result has presenceRequired: false, call endpoint.create with the PIN body.
3. Otherwise ask the person at the device to press the R button. If codeDisplayed is true, they can type the 8-digit code from the screen instead.
4. To continue after a button press without asking, poll endpoint.pollPinPresence until pressed is true.
5. Before expiresAt, call endpoint.create with challengeId. For a typed code, also send authorizationCode.
6. If the call fails with endpoint_presence_not_pressed or endpoint_presence_rejected, retry with the same challenge. If it fails with endpoint_presence_invalid, start again at step 1.
7. If the confirmation is abandoned, call endpoint.cancelPinPresence with challengeId.

WireGuard

{
  "workspaceId": "$workspaceId",
  "kind": "wireguard",
  "name": "TRB256",
  "publicKey": "$wireGuardPublicKey"
}

publicKey is the device’s WireGuard public key: 44 base64 characters ending in =, the canonical base64 of 32 bytes, so the character before = is one of AEIMQUYcgkosw048. Any other value fails input validation. Optional port defaults to 502. A WireGuard body has no hostname or pinCode.

The VPN address is assigned a few seconds after create. Until then endpoint.wireGuardConfig fails with endpoint_vpn_pending; afterwards it returns the peer configuration. A public key belongs to at most one WireGuard endpoint (endpoint_public_key_in_use). endpoint_vpn_db_unavailable means VPN addresses cannot be assigned or read at the moment.

MC252 HTTP status

endpoint.mc252Status takes { "workspaceId": "$workspaceId" } and returns endpoints, each with endpointId and status. Only MC252 PIN endpoints are included. Disabled endpoints, and endpoints never observed, have a null status. Workspace read permission is required.

endpoint.watchMc252Status takes the same input and streams a snapshot, then change events. Each change contains endpointId and status. Subscriptions end if workspace membership changes. This HTTP status is separate from the Modbus status returned by endpoint.status.

Status includes reachability (online, offline, or unknown), checkedAt, lastContactAt, firmware, firmwareCheckedAt, scheduler, and card. Overvis schedules checks every 15 seconds and gives HTTP requests five seconds to respond. Busy devices and stale observations become unknown; a check that could not run does not make a device offline. Queue delays and load can extend the detection time. Retained firmware, scheduler, and card data may describe the last successful check rather than the current device state. Firmware is fetched first and again after an observed reconnect.

Device web interface

Opening a device’s web interface works only in the web app: it is not part of the API inventory. Editors, admins, and owners open Device UI from Setup for a PIN or WireGuard endpoint whose device is connected to the Overvis VPN.

Update

endpoint.update changes only the fields it receives. hostname is refused on PIN and WireGuard endpoints. port is ignored on PIN (always 502) and editable on Direct and WireGuard. kind, publicKey, pinCode, and a PIN endpoint’s SKU and device metadata cannot change.

{ "id": "$endpointId", "name": "PLC line 1" }

{ "id": "$endpointId", "hostname": "plc-backup.example.com", "port": 502 }

settings.tcp needs every key when it is sent:

{
  "id": "$endpointId",
  "settings": {
    "tcp": {
      "maxTcpPacketSize": 1460,
      "maxParallelInflightAdus": 8,
      "maxQueuedAdus": 1000,
      "connectTimeoutMs": 10000,
      "connectRetryDelayMs": 5000,
      "totalRequestTimeoutMs": 30000,
      "responseAwaitTimeoutMs": 5000,
      "tcpKeepaliveEveryMs": 30000,
      "disconnectAfterProtocolErrorCount": 3
    }
  }
}

Modbus reads by address

{
  "endpointId": "$endpointId",
  "items": [
    { "unitId": 1, "table": "input-register", "address": 100, "quantity": 2 },
    { "unitId": 1, "table": "coil", "address": 0, "quantity": 8 }
  ]
}

endpoint.modbusRead needs the editor, admin, or owner role. table is coil, discrete-input, holding-register, or input-register; one call takes 1–32 items. A read of more than 125 registers or 2000 bits, or past address 65535, fails the call with endpoint_modbus_read_invalid. The result has one entry per item, in order: { "status": "ok", "values": [...] } with registers as 0–65535 and bits as 0 or 1, or { "status": "error", "error": {...} } with a runtime error for that item alone. When the reads cannot be sent at all, the call fails with endpoint_modbus_read_unavailable.

Connection failure details

endpoint.status and endpoint.watchStatus return an optional lastError.reason alongside the technical message and timestamp. Reasons include endpoint_vpn_pending, endpoint_connect_failed, endpoint_connection_lost, and protocol_error. Older records have no reason. The UI shows localized guidance from the reason; the traffic log keeps the diagnostic text.

A connected status describes the TCP connection. It does not confirm that a parameter request is allowed. A device may close the socket when VPN access is disabled, and a Modbus exception may indicate protected access or an unsupported address. Only a successful read shows that access is allowed.