Skip to the content.

VxDesk — API Contract (backend ↔ frontend)

Base URL: http://127.0.0.1:8765. All REST paths below are prefixed with /api. WebSocket: /ws/.... CORS: allow http://localhost:* and http://127.0.0.1:* (dev only). The Vite dev server proxies /api and /ws to the backend, so the frontend uses relative paths.

System

GET /api/system/info

{
  "version": "0.1.0",
  "os": "windows",
  "python": "3.12.14",
  "capture": {"backend": "dxcam", "gpu": true, "fps_hint": 120},
  "ocr": {"available": true, "backend": "rapidocr-onnxruntime", "gpu": true, "provider": "DmlExecutionProvider"},
  "gpu": {"name": "AMD Radeon (TM) Graphics", "directml": true},
  "screens": [{"index": 0, "x": 0, "y": 0, "width": 1920, "height": 1080}]
}

Every capability probe must degrade gracefully (e.g. "backend": "mss", "gpu": false).

Workflows

Workflow JSON shape (what the editor saves/loads):

{
  "id": "wf_8f3a...",
  "name": "My workflow",
  "description": "",
  "nodes": [
    {"id": "n1", "type": "trigger.manual", "name": "Start", "position": {"x": 0, "y": 0},
     "params": {}, "disabled": false}
  ],
  "edges": [
    {"id": "e1", "source": "n1", "target": "n2", "sourceHandle": "default"}
  ],
  "variables": {"my_var": "initial"}
}

Endpoints:

Runs

{"run_id": "...", "workflow_id": "...", "status": "running|success|failed|stopped",
 "started_at": "...", "finished_at": null, "error": null,
 "node_states": {"n1": {"status": "success", "output": {...}, "duration_ms": 12, "error": null}}}

WS /ws/runs/{run_id}

Server pushes JSON events:

{"event": "run_started",   "run_id": "..."}
{"event": "node_started",  "node_id": "n2", "name": "Find button"}
{"event": "node_finished", "node_id": "n2", "status": "success", "output": {...}, "duration_ms": 34}
{"event": "log",           "node_id": "n2", "level": "info", "message": "..."}
{"event": "run_finished",  "status": "success", "error": null}

A client connecting mid-run must first receive a snapshot event with the same shape as GET /api/runs/{run_id}, then live events.

Capture / vision utilities (used by the editor's picker & node debugging)

Template assets

Node catalog (for the editor)

{"nodes": [
  {"type": "vision.find_image", "category": "vision", "label": "Find Image",
   "description": "...", "icon": "image",
   "branch_handles": ["found", "not_found"],
   "params": [
     {"name": "template", "label": "Template", "kind": "template", "required": true},
     {"name": "threshold", "label": "Threshold", "kind": "number", "default": 0.8, "min": 0.1, "max": 1.0, "step": 0.05},
     {"name": "region", "label": "Region", "kind": "region", "required": false}
   ]}
]}

kind ∈ string | text | number | boolean | select | template | region | point | csv | code | keys. select params include options: [{value, label}]. branch_handles omits the implicit "default" handle. The frontend fetches this at startup and must keep a bundled fallback copy in case the backend is unreachable.

Conventions