Protocol overview

veriCue speaks length-prefixed JSON over TCP:

+--------+--------+--------+--------+----- ... -----+
|        4-byte big-endian length          |    UTF-8 JSON payload    |
+--------+--------+--------+--------+----- ... -----+

Maximum payload size: 16 MB.

Connection lifecycle

1. TCP connect to the server's listening port (default 4242).
2. Handshake (mandatory first message) negotiating protocol version and authentication.
3. Regular request/response commands.

All commands sent before a successful handshake are rejected with authentication_required (code 1007).

Message types

Every message has a type field:

Type	Direction	Description
request	Client → Server	A command invocation with an id
response	Server → Client	Success reply matching the request id
error	Server → Client	Error reply matching the request id
event	Server → Client	Asynchronous push - no id, sent for active subscriptions

Request shape

{
  "v": 1,
  "id": "unique-string",
  "type": "request",
  "method": "find_object",
  "params": { "path": "MainWindow/okButton" }
}

Response shape

{
  "v": 1,
  "id": "unique-string",
  "type": "response",
  "result": {
    "className": "QPushButton",
    "objectName": "okButton",
    "path": "MainWindow/okButton"
  }
}

Error shape

{
  "v": 1,
  "id": "unique-string",
  "type": "error",
  "error": {
    "code": 2001,
    "message": "Object not found: MainWindow/nope"
  }
}

Error codes are documented in Error codes.

Event shape

{
  "v": 1,
  "type": "event",
  "subscription_id": "sub-42",
  "event": "signal_emitted",
  "path": "MainWindow/okButton",
  "data": {
    "signal": "clicked",
    "args": []
  },
  "timestamp": "2026-06-21T10:42:13.001Z"
}

See Push events for the full subscription model.

Path syntax

Objects are addressed by their path in the QObject hierarchy:

TopLevelWindow/centralWidget/okButton

• Segments are separated by /.
• Each segment is either the object's objectName or ClassName#N for unnamed objects.
• The first segment is a top-level window (a QWidget from QApplication::topLevelWidgets() or a QQuickWindow).