REST API & WebSocket Event Protocol Specification

Wizard exposes a high-performance control plane over HTTP/REST and bidirectional WebSockets. This reference documents the transport models, authentication headers, session management, and the streaming event protocol.

Interactive OpenAPI 3.1 documentation is served live on your instance at http://localhost:8000/docs.

1. Authentication & Session Headers

2. Core REST Endpoints

System, Health & SRE Diagnostics

• GET /health: Comprehensive cluster readiness check (alias to /health/ready).
• GET /health/live: Kubernetes process liveness probe returning HTTP 200 {"status": "ok"} when the process is alive.
• GET /health/ready: Kubernetes cluster readiness probe that actively validates SQLite writeability, Redis reachability, and Docker socket health. Returns HTTP 503 if any critical dependency is degraded.
• GET /metrics: Prometheus-compatible exposition format reporting Time-To-First-Token (TTFT), rolling p50/p90/p95/p99 latency quantiles, token generation counters, and error budgets.
• GET /api/config: Capabilities manifest used by the frontend to render feature workbenches (data modes, sandbox capabilities, active tier, embedding status).
• PATCH /api/config: Dynamically updates runtime configuration (API_PROVIDER, DATA_MODE, EMBEDDING_PROVIDER, EMBEDDING_REMOTE_MODEL, etc.) with atomic .env persistence and dynamic embedding service re-warming.
• GET /api/sandbox/selftest: Probes live OS sandbox enforcement (Landlock, seccomp, seatbelt) and returns containment verdict.

Session Lifecycle

• POST /api/session: Creates a new isolated analytical session. Returns SessionResponse with unique session_id.
• GET /api/session: Returns current session state, loaded tables, models, and data privacy policies.
• DELETE /api/session: Destroys the session, drops ephemeral dataframes, and terminates execution sandboxes.
• POST /api/session/reset: Resets Python execution variables while preserving loaded datasets.

Datasets & Ingestion

• POST /api/datasets: Ingests multipart files (CSV, Parquet, Excel, Feather, JSON) into the session workspace.
  • Query parameter clean=true|false: Triggers automated data cleaning pass.
• GET /api/datasets: Lists all mounted tables and preview metadata in the session catalog.
• DELETE /api/datasets/{name}: Unmounts a table and purges cached vector embeddings.

Skills & Knowledge

• GET /api/skills: Returns all discovered built-in, user, and project skills.
• POST /api/skills/install: Stages and imports an external skill from a Git URL.

Analytical Turn Execution

• POST /api/chat: Executes a synchronous analytical turn and returns the complete synthesized response with code and citations. Includes idempotency locking.
• POST /api/chat/stream: Server-Sent Events (SSE) streaming endpoint for environments where bidirectional WebSockets are restricted or subject to backpressure shedding. Returns streaming event frames identical to /ws/chat.

3. WebSocket Streaming Protocol (/ws/chat)

For interactive real-time UX, clients establish a persistent WebSocket connection to /ws/chat. The server streams granular event frames as the agent observes, reasons, and executes:

{
  "type": "iteration_start",
  "iteration": 1,
  "budget": 12,
  "timestamp": 1787907459.12
}

Complete Event Frame Specification:

4. Subagent Branching Multiplexing

When an analytical task fans out into parallel sub-investigations (e.g. comparing 4 marketing channels simultaneously), each branch reuses the same event frames, qualified by a branch field:

{
  "type": "code",
  "branch": "channel_search_paid",
  "code": "df[df['channel'] == 'paid_search'].describe()"
}

The frontend multiplexes these events into concurrent subagent cards without requiring separate WebSocket connections.