{"openapi":"3.1.0","info":{"title":"WebSocket Session Manager API","description":"Stateful WebSocket session registry with per-connection Shannon entropy delta tracking for schema divergence detection in agentic workflows.","version":"1.0.0"},"paths":{"/ws-sessions/open":{"post":{"summary":"open_websocket_session","operationId":"open_websocket_session_ws_sessions_open_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenSessionRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]}}},"/ws-sessions/{session_id}/send-frame":{"post":{"summary":"send_typed_ws_frame","operationId":"send_typed_ws_frame_ws_sessions__session_id__send_frame_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","minLength":32,"maxLength":32,"title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendFrameRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendFrameResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ws-sessions/{session_id}/drain-frames":{"post":{"summary":"drain_ws_frame_buffer","operationId":"drain_ws_frame_buffer_ws_sessions__session_id__drain_frames_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","minLength":32,"maxLength":32,"title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrainFramesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrainFramesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ws-sessions/{session_id}/telemetry":{"post":{"summary":"inspect_ws_session_telemetry","operationId":"inspect_ws_session_telemetry_ws_sessions__session_id__telemetry_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","minLength":32,"maxLength":32,"title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ws-sessions/{session_id}/close":{"post":{"summary":"close_websocket_session","operationId":"close_websocket_session_ws_sessions__session_id__close_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","minLength":32,"maxLength":32,"title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseSessionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseSessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/health":{"get":{"summary":"Liveness probe - no auth required","operationId":"_nexus_health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response  Nexus Health Check Health Get"}}}}},"security":[]}},"/stripe/webhook":{"post":{"summary":" Nexus Stripe Webhook","operationId":"_nexus_stripe_webhook_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"CloseSessionRequest":{"properties":{"status_code":{"type":"integer","maximum":4999.0,"minimum":1000.0,"title":"Status Code","description":"WebSocket close status code per RFC 6455.","default":1000},"reason":{"type":"string","maxLength":123,"title":"Reason","description":"Optional close reason string (max 123 bytes per RFC 6455).","default":""}},"type":"object","title":"CloseSessionRequest"},"CloseSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"target_url":{"type":"string","title":"Target Url"},"final_state":{"$ref":"#/components/schemas/WsConnectionState"},"frames_sent":{"type":"integer","title":"Frames Sent"},"frames_received":{"type":"integer","title":"Frames Received"},"terminal_entropy":{"type":"number","title":"Terminal Entropy"},"schema_violations":{"type":"integer","title":"Schema Violations"},"uptime_seconds":{"type":"number","title":"Uptime Seconds"},"message":{"type":"string","title":"Message"}},"type":"object","required":["session_id","target_url","final_state","frames_sent","frames_received","terminal_entropy","schema_violations","uptime_seconds","message"],"title":"CloseSessionResponse"},"DrainFramesRequest":{"properties":{"max_frames":{"type":"integer","maximum":256.0,"minimum":1.0,"title":"Max Frames","description":"Maximum number of buffered frames to return in a single drain.","default":32}},"type":"object","title":"DrainFramesRequest"},"DrainFramesResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"frames_returned":{"type":"integer","title":"Frames Returned"},"frames":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Frames"},"buffer_remaining":{"type":"integer","title":"Buffer Remaining"}},"type":"object","required":["session_id","frames_returned","frames","buffer_remaining"],"title":"DrainFramesResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OpenSessionRequest":{"properties":{"target_url":{"type":"string","minLength":6,"title":"Target Url","description":"WebSocket URL to connect to (ws:// or wss://)"},"connect_timeout_seconds":{"type":"number","maximum":60.0,"minimum":0.5,"title":"Connect Timeout Seconds","description":"Maximum seconds to wait for the handshake to complete.","default":10.0},"extra_headers":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Extra Headers","description":"Optional HTTP headers for the upgrade request (e.g. auth tokens)."}},"type":"object","required":["target_url"],"title":"OpenSessionRequest"},"OpenSessionResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"target_url":{"type":"string","title":"Target Url"},"state":{"$ref":"#/components/schemas/WsConnectionState"},"opened_at_unix":{"type":"number","title":"Opened At Unix"},"message":{"type":"string","title":"Message"}},"type":"object","required":["session_id","target_url","state","opened_at_unix","message"],"title":"OpenSessionResponse"},"SendFrameRequest":{"properties":{"payload":{"type":"string","maxLength":131072,"minLength":0,"title":"Payload","description":"Frame payload. For binary frames, pass hex-encoded string."},"frame_type":{"$ref":"#/components/schemas/WsFrameType","description":"'text' sends payload as UTF-8 string; 'binary' decodes payload from hex.","default":"text"}},"type":"object","required":["payload"],"title":"SendFrameRequest"},"SendFrameResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"frame_type":{"$ref":"#/components/schemas/WsFrameType"},"payload_bytes":{"type":"integer","title":"Payload Bytes"},"entropy_after":{"type":"number","title":"Entropy After"},"entropy_delta":{"type":"number","title":"Entropy Delta"},"schema_valid":{"type":"boolean","title":"Schema Valid"},"sent_at_unix":{"type":"number","title":"Sent At Unix"}},"type":"object","required":["session_id","frame_type","payload_bytes","entropy_after","entropy_delta","schema_valid","sent_at_unix"],"title":"SendFrameResponse"},"TelemetryResponse":{"properties":{"session_id":{"type":"string","title":"Session Id"},"target_url":{"type":"string","title":"Target Url"},"state":{"$ref":"#/components/schemas/WsConnectionState"},"uptime_seconds":{"type":"number","title":"Uptime Seconds"},"frames_sent":{"type":"integer","title":"Frames Sent"},"frames_received":{"type":"integer","title":"Frames Received"},"current_entropy":{"type":"number","title":"Current Entropy"},"rolling_entropy_mean":{"type":"number","title":"Rolling Entropy Mean"},"rolling_entropy_std":{"type":"number","title":"Rolling Entropy Std"},"rolling_entropy_max":{"type":"number","title":"Rolling Entropy Max"},"cumulative_entropy_bits":{"type":"number","title":"Cumulative Entropy Bits"},"schema_violations":{"type":"integer","title":"Schema Violations"},"schema_violation_rate":{"type":"number","title":"Schema Violation Rate"},"inbound_buffer_depth":{"type":"integer","title":"Inbound Buffer Depth"}},"type":"object","required":["session_id","target_url","state","uptime_seconds","frames_sent","frames_received","current_entropy","rolling_entropy_mean","rolling_entropy_std","rolling_entropy_max","cumulative_entropy_bits","schema_violations","schema_violation_rate","inbound_buffer_depth"],"title":"TelemetryResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WsConnectionState":{"type":"string","enum":["CONNECTING","OPEN","CLOSING","CLOSED"],"title":"WsConnectionState"},"WsFrameType":{"type":"string","enum":["text","binary"],"title":"WsFrameType"}}}}