< still under construction >

Overview

The HyperFlow Control API implements a sophisticated long-polling pattern for real-time communication between client applications (such as embeddable chatbots) and running flow-graphs on the server. This architecture creates a persistent, bidirectional communication channel that enables responsive user interactions without the complexity of WebSockets.

Key Characteristics

• Stateful Sessions: Each interaction maintains context through session IDs
• Real-time Updates: Server can push updates immediately when available
• Resilient Design: Automatic reconnection and session recovery
• Streaming Support: Progressive LLM response delivery for better UX

Architecture

Core Endpoints

POST /api/flowgraph/control/start
POST /api/flowgraph/control/progress
POST /api/flowgraph/control/streaming
POST /api/hyperflow/uploadContent

Data Flow Model

┌─────────────┐                           ┌─────────────────┐
│   Client    │                           │     Server      │
│ (Chatbot)   │                           │  (Flow-graph)   │
└─────┬───────┘                           └────────┬────────┘
      │                                             │
      │  1. POST /control/start                     │
      │  {flowGraphID, queryParams}                 │
      │─────────────────────────────────────────────>
      │                                             │
      │  {sessionID, stepIndex: 1, responses:[...]} │
      <─────────────────────────────────────────────│
      │                                             │
      │  2. POST /control/progress                  │
      │  {sessionID, stepIndex: 1, progress:[...]}  │
      │─────────────────────────────────────────────>
      │                                             │
      │         [Server holds connection]           │
      │              ...waiting...                  │
      │                                             │
      │  {sessionID, stepIndex: 2, responses:[...]} │
      <─────────────────────────────────────────────│
      │                                             │
      │  3. Immediate next /control/progress        │
      │  {sessionID, stepIndex: 2, progress:[       │
      │    {type: "updatePoll"}                     │
      │  ]}                                         │
      │─────────────────────────────────────────────>
      │                                             │

Session Management

Session Lifecycle

• Created: Via /control/start with flowGraphID
• Persisted: Sessions remain active indefinitely (no timeout)
• Identified: Unique sessionID for each conversation
• Context: Maintains conversation state and query parameters

Query Parameters