Add documentation for exec websocket (#9679)

website/content/api-docs/allocations.mdx

@@ -712,3 +712,94 @@ $ curl -X POST -d '{"Task": "redis" }' \
 ```json
 {}
 ```
+
+## Exec Allocation
+
+This endpoint executes a command inside the isolation container where an allocation is running.
+It opens a WebSocket to transmit input to and output from the command.
+
+| Method | Path                       | Produces                   |
+| ------ | -------------------------- | -------------------------- |
+| `WebSocket` | `/v1/client/allocation/:alloc_id/exec` | WebSocket JSON streams |
+
+The table below shows this endpoint's support for
+[blocking queries](/api/index.html#blocking-queries) and
+[required ACLs](/api/index.html#acls).
+
+| Blocking Queries | ACL Required         |
+| ---------------- | -------------------- |
+| `NO`            | `namespace:alloc-exec` (and `namespace:alloc-node-exec` if target task uses raw_exec driver) |
+
+### Parameters
+
+- `:alloc_id` `(string: <required>)`- Specifies the UUID of the allocation. This
+  must be the full UUID, not the short 8-character one. This is specified as
+  part of the path.
+- `command` `(string: <required>)` - Specifies the command to be executed.  This
+  must be a JSON-encoded array of the command to be executed, e.g. `["echo", "hi"]`
+  or `["/bin/bash"]`. This is specified as a query parameter.
+- `task` `(string: <required>)` - Specifies the task name, as a query parameter.
+- `tty` `(bool: false)` - Specifies whether a TTY is allocated for this task, as
+  a query parameter.
+- `ws_handshake` `(bool: false)` - Specifies whether to expect the authentication
+  token in the first frame, as a query parameter.
+
+### Request Frames
+
+Request frames represent the `stdin` stream from the command as well as TTY resize events.
+When `?ws_handshake=true`, the first request frame must contain the authentication token.
+
+The following are valid formats:
+
+```
+# sending authentication token
+{"version":1,"auth_token":"fc3c1968-8d31-5c50-9617-3db2e19ef32e"}
+
+# sending stdin data
+{"stdin": {"data": "...base64 encoded string of bytes ..."}}
+
+# indicating stdin is closed
+{"stdin": {"close": true}}
+
+# indicating that TTY was resized
+{"tty_size": {"height": <characters>, "width": <characters>}}
+
+# basic application-level heartbeat
+{}
+```
+
+### Response Frames
+
+Response frames represent `stdout` and `stderr` output from the command as well as exit codes:
+
+```
+# transferring stdout data
+{"stdout": {"data": "...base64 encoded string of bytes ..."}}
+
+# signaling that host closed stdout
+{"stdout": {"close": true}}
+
+# transferring stderr data
+{"stderr": {"data": "...base64 encoded string of bytes ..."}}
+
+# signaling that host closed stderr
+{"stderr": {"close": true}}
+
+# signaling process exited
+{"exited": true, "result": {"exit_code": <exit_code_int>}}
+
+# basic application-level heartbeat
+{}
+```
+
+### Sample Request and Response
+
+Request and response frames encompass the full range of terminal emulator inputs and outputs, including the control characters necessary to render interactive applications. The example response includes instances of the ANSI “control sequence introducer” (CSI), which is ASCII code 27 followed by `[`.
+
+```
+# \x12: form feed, to clear terminal
+{"stdin":{"data":"DA=="}}
+
+# "\x1b[H\x1b[2J$ ":
+# CSI-H (move cursor to top left corner), CSI-2J (clear entire screen), print "$ "
+{"stdout":{"data":"G1tIG1sySiQg"}}