REST and WebSocket API

Overview

Everything the CONNECT panel does, it does through a documented HTTP and WebSocket surface on port 5100. Your own tools can use the same surface: read signals, write signals, create interfaces, run discovery.

Every request follows the access rule: local callers pass, remote callers present X-API-Key.

Signal channel

ws://<host>:5100/ws          wss:// behind a TLS reverse proxy

This is the live channel — the same one the browser HMI uses. It speaks the rv WebSocket Realtime v2 protocol, JSON over WebSocket, which is also spoken by realvirtual Core and the ctrlX bridge.

Connection sequence

On connect the client receives a complete baseline before anything else:

import_answer — all signal types and their current values, so the client can register every signal correctly without waiting.
data — a full snapshot of current values.
From then on: data messages carrying only what changed, on a fixed 10 ms tick.

The baseline is always sent before the client joins the broadcast, so a delta can never overtake it.

Messages

Gateway to client

Type	Payload
`import_answer`	Signal types and current values
`data`	Signal values — full snapshot on connect, deltas afterwards
`config_answer`	The configuration, in response to `config_get`
`discover_answer`	Discovery results for one interface

Client to gateway

Type	Effect
`data`	Values are written into the gateway — this is how a client commands the machine
`import_request`	Requests a fresh `import_answer`
`config_get`	Requests the configuration
`subscribe`	Signal subscription hint

A value message looks like this:

{
  "type": "data",
  "version": 2,
  "signals": { "Conveyor1Running": true, "Actual_Temp": 234, "Motor1_Speed": 1.45 }
}

Behaviour worth relying on

Only the latest value per signal per tick is sent; a value that changes and reverts within one tick collapses to its current value, which is correct for an HMI.
The gateway sends nothing while nothing changes — an idle connection costs nothing.
A heartbeat runs every 30 seconds; clients idle for 90 seconds are closed.
A configuration change resends a full snapshot, so no client is left with a stale set.

Authentication for a WebSocket upgrade uses ?apikey=<key>, because a browser cannot set headers on a handshake.

REST endpoints

Method and path	Purpose
`GET /health`	Liveness, version, build and capability flags — answers without authentication
`GET /health/detail`	Signal and client counts, license state
`GET /signals`	All signals with types, count and version
`GET /config`	The complete configuration
`PUT /config`	Replace the complete configuration
`GET /config/interfaces`	List interfaces
`POST /config/interfaces`	Create an interface
`PUT /config/interfaces/{id}`	Replace an interface — also used for tag-table re-import
`DELETE /config/interfaces/{id}`	Remove an interface
`POST /signals/validate`	Validate a protocol address without saving anything
`POST /discover/{id}/start`	Run discovery on a live interface
`POST /discover/{id}/bind`	Register and persist selected discovered signals
`GET /interface-types`	Available interface types and what each one supports

Additional endpoints exist for the optional services: /history/* for recorded data, /cad/step-to-glb and /cad/jt-to-glb for CAD conversion, /diagnose and /comments for AI diagnosis, and /update/* for updates.

Configuration writes are persisted atomically and applied by hot-reload: affected interfaces restart, the gateway does not.

Example

# Is the gateway up?
curl http://localhost:5100/health

# All current signals
curl -H "X-API-Key: $KEY" http://localhost:5100/signals

# Validate an address before creating a signal
curl -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
     -d '{"interfaceType":"S7","protocolAddress":"DB1.DBX0.0","dataType":"Bool"}' \
     http://localhost:5100/signals/validate

Signal types on the wire

Wire type	Direction
`PLCInputBool`, `PLCInputInt`, `PLCInputFloat`	Written by realvirtual, read by the PLC
`PLCOutputBool`, `PLCOutputInt`, `PLCOutputFloat`	Written by the PLC, read by realvirtual

See configuring interfaces for what that means in practice.