diff --git a/docs/api.md b/docs/api.md
index 79b65b9..7fbdb3b 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -72,3 +72,9 @@ The back end exposes a number of API endpoints which are referenced in the table
 | POST   | /api/files/delete | Delete file      |
 | POST   | /api/files/edit   | Edit file        |
 | POST   | /api/files/mkdir  | Create directory |
+
+## WebSocket
+
+Real-time communication is handled via WebSocket at `/api/ws` using Protocol Buffers.
+
+See [websocket.md](websocket.md) for the full WebSocket API documentation.
diff --git a/docs/websocket.md b/docs/websocket.md
new file mode 100644
index 0000000..b165179
--- /dev/null
+++ b/docs/websocket.md
@@ -0,0 +1,47 @@
+# WebSocket API
+
+The ESP32 exposes a WebSocket endpoint at `/api/ws` for real-time bidirectional communication using Protocol Buffers (protobuf).
+
+## Connection
+
+Connect to the WebSocket at:
+
+```
+ws://<device-ip>/api/ws
+```
+
+All messages are binary-encoded protobuf `Message` wrappers defined in `platform_shared/message.proto`.
+
+## Message Flow
+
+The WebSocket supports three communication patterns:
+
+1. **Client to Server**: Commands like controller input, mode changes, servo control
+2. **Server to Client**: Periodic data broadcasts like IMU, system metrics, RSSI, servo angles
+3. **Request-Response**: Use `socket.request()` for operations requiring a response
+
+## Example: Sending Controller Input
+
+```typescript
+import { Message, ControllerData } from "./proto/message";
+
+const input: ControllerData = {
+  left: { x: 0.5, y: 0.0 },
+  right: { x: 0.0, y: 0.0 },
+  height: 0.1,
+  speed: 1.0,
+  s1: 0.0,
+};
+
+const message = Message.encode({ ControllerData: input }).finish();
+socket.send(message);
+```
+
+## Example: Request-Response
+
+```typescript
+const response = await socket.request({ imuCalibrateExecute: {} });
+const result = response.imuCalibrateData;
+```
+
+See `platform_shared/message.proto` for all available message types and their definitions.