REST API OpenAPI spec (#612)

* OpenAPI spec in specs/api.  Checked lint with redoc.

specs/api/paths/websocket.yaml

@@ -0,0 +1,185 @@
+get:
+  tags:
+    - WebSocket
+  summary: WebSocket - multiplexed service interface
+  description: |
+    WebSocket interface providing multiplexed access to all TrustGraph services over a single persistent connection.
+
+    ## Overview
+
+    The WebSocket API provides access to the same services as the REST API but with:
+    - **Multiplexed**: Multiple concurrent requests over one connection
+    - **Asynchronous**: Non-blocking request/response with ID matching
+    - **Efficient**: Reduced overhead compared to HTTP
+    - **Real-time**: Low latency bidirectional communication
+
+    ## Connection
+
+    Establish WebSocket connection to:
+    ```
+    ws://localhost:8088/api/v1/socket
+    ```
+
+    ## Message Protocol
+
+    All messages are JSON objects with the following structure:
+
+    ### Request Message Format
+
+    **Global Service Request** (no flow parameter):
+    ```json
+    {
+      "id": "req-123",
+      "service": "config",
+      "request": {
+        "operation": "list",
+        "type": "flow"
+      }
+    }
+    ```
+
+    **Flow-Hosted Service Request** (with flow parameter):
+    ```json
+    {
+      "id": "req-456",
+      "service": "agent",
+      "flow": "my-flow",
+      "request": {
+        "question": "What is quantum computing?",
+        "streaming": true
+      }
+    }
+    ```
+
+    **Request Fields**:
+    - `id` (string, required): Client-generated unique identifier for this request within the session. Used to match responses to requests.
+    - `service` (string, required): Service identifier (e.g., "config", "agent", "document-rag"). Same as `{kind}` in REST URLs.
+    - `flow` (string, optional): Flow ID for flow-hosted services. Omit for global services.
+    - `request` (object, required): Service-specific request payload. Same structure as REST API request body.
+
+    ### Response Message Format
+
+    **Success Response**:
+    ```json
+    {
+      "id": "req-123",
+      "response": {
+        "chunk-type": "answer",
+        "content": "Quantum computing uses...",
+        "end-of-stream": false
+      }
+    }
+    ```
+
+    **Error Response**:
+    ```json
+    {
+      "id": "req-123",
+      "error": {
+        "type": "gateway-error",
+        "message": "Flow not found"
+      }
+    }
+    ```
+
+    **Response Fields**:
+    - `id` (string, required): Matches the `id` from the request. Client uses this to correlate responses.
+    - `response` (object, conditional): Service-specific response payload. Same structure as REST API response. Present on success.
+    - `error` (object, conditional): Error information with `type` and `message` fields. Present on failure.
+
+    ## Service Routing
+
+    The WebSocket protocol routes to services using message parameters instead of URL paths:
+
+    | REST Endpoint | WebSocket Message |
+    |--------------|-------------------|
+    | `POST /api/v1/config` | `{"service": "config"}` |
+    | `POST /api/v1/flow/{flow}/service/agent` | `{"service": "agent", "flow": "my-flow"}` |
+
+    **Global Services** (no `flow` parameter):
+    - `config` - Configuration management
+    - `flow` - Flow lifecycle and blueprints
+    - `librarian` - Document library management
+    - `knowledge` - Knowledge graph core management
+    - `collection-management` - Collection metadata
+
+    **Flow-Hosted Services** (require `flow` parameter):
+    - AI services: `agent`, `text-completion`, `prompt`, `document-rag`, `graph-rag`
+    - Embeddings: `embeddings`, `graph-embeddings`, `document-embeddings`
+    - Query: `triples`, `objects`, `nlp-query`, `structured-query`
+    - Data loading: `text-load`, `document-load`
+    - Utilities: `mcp-tool`, `structured-diag`
+
+    ## Request/Response Schemas
+
+    The `request` and `response` fields use **identical schemas** to the REST API for each service.
+    See individual service documentation for detailed request/response formats.
+
+    ## Multiplexing and Asynchronous Operation
+
+    Multiple requests can be in flight simultaneously:
+    - Client sends requests with unique `id` values
+    - Server processes requests concurrently
+    - Responses arrive asynchronously and may be out of order
+    - Client matches responses to requests using the `id` field
+    - No head-of-line blocking
+
+    **Example concurrent requests**:
+    ```json
+    {"id": "req-1", "service": "config", "request": {...}}
+    {"id": "req-2", "service": "agent", "flow": "f1", "request": {...}}
+    {"id": "req-3", "service": "document-rag", "flow": "f2", "request": {...}}
+    ```
+
+    Responses may arrive in any order: `req-2`, `req-1`, `req-3`
+
+    ## Streaming Responses
+
+    Services that support streaming (e.g., agent, RAG) send multiple response messages with the same `id`:
+    ```json
+    {"id": "req-1", "response": {"chunk-type": "thought", "content": "...", "end-of-stream": false}}
+    {"id": "req-1", "response": {"chunk-type": "answer", "content": "...", "end-of-stream": false}}
+    {"id": "req-1", "response": {"chunk-type": "answer", "content": "...", "end-of-stream": true}}
+    ```
+
+    The `end-of-stream` flag (or service-specific completion flag) indicates the final message.
+
+    ## Authentication
+
+    When `GATEWAY_SECRET` is set, include bearer token:
+    - As query parameter: `ws://localhost:8088/api/v1/socket?token=<token>`
+    - Or in WebSocket subprotocol header
+
+    ## Benefits Over REST
+
+    - **Lower latency**: No TCP/TLS handshake per request
+    - **Connection reuse**: Single persistent connection
+    - **Reduced overhead**: No HTTP headers per message
+    - **True streaming**: Bidirectional real-time communication
+    - **Efficient multiplexing**: Concurrent operations without connection pooling
+
+  operationId: websocketConnection
+  security:
+    - bearerAuth: []
+  parameters:
+    - name: Upgrade
+      in: header
+      required: true
+      schema:
+        type: string
+        enum: [websocket]
+      description: WebSocket upgrade header
+    - name: Connection
+      in: header
+      required: true
+      schema:
+        type: string
+        enum: [Upgrade]
+      description: Connection upgrade header
+  responses:
+    '101':
+      description: Switching Protocols - WebSocket connection established
+    '401':
+      $ref: '../components/responses/Unauthorized.yaml'
+    '500':
+      $ref: '../components/responses/Error.yaml'