Remote API access

Pick the correct service

The system console and Robot WebUI are separate FastAPI applications. Both implement /api/health and /ws, but their resources, events and command semantics differ. A healthy console does not establish that the robot ROS adapter is connected.

Use explicit base URLs for each application:

export CONSOLE_URL='http://ROBOT_HOST:CONSOLE_PORT'
export ROBOT_UI_URL='http://ROBOT_HOST:WEBUI_PORT'
curl --fail-with-body "$CONSOLE_URL/api/health"
curl --fail-with-body "$ROBOT_UI_URL/api/health"

Replace host and ports with the actual deployment values. The console README uses port 18091 for development and 8088 in its production example. Robot WebUI uses 18081 for Vite development and 18080 in its production-style example. Reverse proxies and Compose publishing can change the address exposed remotely.

The documentation website is static. Its domain is not a robot API endpoint and must not receive robot credentials.

Console health and snapshots

GET /api/health returns ok, service, version, uptimeSec, and the connected client count. It also marks the console active for refresh scheduling. GET /api/system/summary aggregates cached resource, service, adapter, route, audio, USB and Jetson information. Individual resource endpoints often read refresh caches; a successful read does not imply a new host probe occurred.

curl --fail-with-body "$CONSOLE_URL/api/system/summary"
curl --fail-with-body "$CONSOLE_URL/api/system/services"
curl --fail-with-body "$CONSOLE_URL/api/network/adapters"

Background tasks

Long-running console operations commonly return a task record while work continues asynchronously. Retrieve a task with GET /api/tasks/{task_id}; unknown IDs return HTTP 404 with detail: Task not found. Follow task.updated WebSocket events to observe completion or failure. Do not treat the initial HTTP response as completion of installation, provisioning, audio routing, or update work.

Console WebSocket

Connect to the console's /ws using ws:// for HTTP or wss:// for HTTPS. Initial events include system.resources and system.services. The handler accepts a client.ping message and returns server.pong, preserving requestId and including server time.

{"type":"client.ping","requestId":"docs-check-1"}

The console WebSocket is an event channel. Its handler does not dispatch the Robot WebUI's teleoperation commands.

Robot control and speech

Robot WebUI uses REST for reads, configuration and storage, /ws for command/event messages, and /ws/audio for duplex PCM. Its command envelope contains a type and an optional requestId. The same command handler is exposed through POST /api/teleops/command. Use the service-specific command documentation before issuing commands; actuator and performance operations can move hardware.

The source communication protocol is head-ros-nodes/ros/webui/COMMUNICATION_PROTOCOL.MD. The source-derived route reference records current handlers; request model definitions preserve typed fields and defaults where declared.

Reachability and access control

Determine bind addresses, published ports, authentication middleware and reverse-proxy policy in the target deployment before connecting. Neither source route presence nor an internal service name proves external reachability. Use an approved private network or SSH forwarding for administrative interfaces where the deployment does not provide authenticated HTTPS.

Evidence: hr_system_console/api/system_console/main.py, head-ros-nodes/ros/webui/api/webui_api/main.py, and component READMEs. No remote state-changing API calls were executed to produce this guide.