Add AsyncAPI spec for websocket (#613)

* AsyncAPI for websocket docs

* Delete old docs

* Update docs/README.md to point to docs site

* Add generated API docs

specs/websocket/components/schemas/ErrorEnvelope.yaml

@@ -0,0 +1,37 @@
+type: object
+description: |
+  WebSocket error message envelope.
+
+  Sent when a request fails. Contains the request ID and error details.
+required:
+  - id
+  - error
+properties:
+  id:
+    type: string
+    description: |
+      Request identifier from the original request that failed.
+    examples:
+      - req-123
+      - request-abc-456
+  error:
+    type: object
+    description: Error information
+    required:
+      - type
+      - message
+    properties:
+      type:
+        type: string
+        description: Error type/category
+        examples:
+          - gateway-error
+          - service-error
+          - timeout
+      message:
+        type: string
+        description: Human-readable error message
+        examples:
+          - Flow not found
+          - Service timeout
+          - Invalid request format

specs/websocket/components/schemas/RequestEnvelope.yaml

@@ -0,0 +1,56 @@
+type: object
+description: |
+  WebSocket request message envelope.
+
+  Wraps service-specific request payloads with routing and correlation metadata.
+required:
+  - id
+  - service
+  - request
+properties:
+  id:
+    type: string
+    description: |
+      Client-generated unique identifier for this request within the WebSocket session.
+      Used to correlate responses with requests in multiplexed async communication.
+      Can be any string, but must be unique per active request.
+    examples:
+      - req-123
+      - request-abc-456
+      - b5f8d9a2-4c3e-11ef-9c8a-0242ac120002
+  service:
+    type: string
+    description: |
+      Service identifier. Same as {kind} in REST API URLs.
+
+      Global services: config, flow, librarian, knowledge, collection-management
+      Flow-hosted services: agent, text-completion, prompt, document-rag, graph-rag,
+      embeddings, graph-embeddings, document-embeddings, triples, objects,
+      nlp-query, structured-query, structured-diag, text-load, document-load, mcp-tool
+    examples:
+      - config
+      - agent
+      - document-rag
+  flow:
+    type: string
+    description: |
+      Flow ID for flow-hosted services. Required for services accessed via
+      /api/v1/flow/{flow}/service/{kind} in REST API.
+
+      Omit this field for global services (config, flow, librarian, knowledge, collection-management).
+    examples:
+      - my-flow
+      - production-flow
+  request:
+    type: object
+    description: |
+      Service-specific request payload. Structure is identical to the request body
+      in the corresponding REST API endpoint.
+
+      See OpenAPI specification for detailed schemas per service.
+    examples:
+      - operation: list
+        type: flow
+      - question: What is quantum computing?
+        streaming: true
+        system-prompt: You are a helpful assistant

specs/websocket/components/schemas/ResponseEnvelope.yaml

@@ -0,0 +1,35 @@
+type: object
+description: |
+  WebSocket response message envelope for successful responses.
+
+  Contains the request ID for correlation and the service-specific response payload.
+required:
+  - id
+  - response
+properties:
+  id:
+    type: string
+    description: |
+      Request identifier from the original request. Client uses this to match
+      responses to requests in multiplexed communication.
+    examples:
+      - req-123
+      - request-abc-456
+  response:
+    type: object
+    description: |
+      Service-specific response payload. Structure is identical to the response body
+      in the corresponding REST API endpoint.
+
+      For streaming services, multiple response messages may be sent with the same `id`.
+      Look for `end-of-stream` or service-specific completion flags to detect the final message.
+
+      See OpenAPI specification for detailed schemas per service.
+    examples:
+      - type: flow
+        keys:
+          - my-flow
+          - production-flow
+      - chunk-type: answer
+        content: Quantum computing uses quantum bits...
+        end-of-stream: false