Qubitz API Documentation

wss://api.qubitz.ai/<endpoint>?api_key=<your_api_key>

{
  "prompt": "Latest AI Trends 2026",
  "company_name": "TestCompany",
  "company_url": "https://example.com/",
  "user_id": "user123",
  "session_id": "session456"
}

{ "type": "status", "message": "Starting multi-agent research system...", "session_id": "..." }

{ "type": "multiagent_step", "step": "research", "message": "Researching sources...", "session_id": "..." }

{ "type": "multiagent_progress", "step": "analysis", "session_id": "..." }

{
  "type": "s3_upload_complete",
  "file_type": "deep_research_markdown",
  "s3_url": "https://qubitz-research-reports.s3.amazonaws.com/.../report.md",
  "session_id": "..."
}

{
  "type": "use_cases_complete",
  "use_cases": [
    {
      "id": "uc_1",
      "title": "Quantum-Safe Payment Processing",
      "description": "...",
      "business_value": "...",
      "impact_score": "High",
      "implementation": "...",
      "estimated_roi": "...",
      "alignment_score": "High"
    }
  ],
  "total_use_cases": 5,
  "session_id": "..."
}

{
  "type": "complete",
  "project_id": "project21",
  "user_id": "user123",
  "s3_deep_research_report_url": "https://...",
  "s3_deep_research_pdf_url": "https://...",
  "s3_AI_discovery_report_url": "https://...",
  "s3_AI_discovery_pdf_url": "https://...",
  "s3_use_cases_pdf_url": "https://...",
  "s3_use_cases_md_url": "https://...",
  "all_s3_urls": {
    "deep_research_report_url": "https://...",
    "deep_research_pdf_url": "https://...",
    "AI_discovery_report_url": "https://...",
    "AI_discovery_pdf_url": "https://...",
    "use_cases_pdf_url": "https://...",
    "use_cases_md_url": "https://..."
  },
  "session_id": "..."
}

{ "type": "keepalive", "timestamp": 1710000000, "message": "Processing..." }

{ "type": "error", "error": "INVALID_QUERY", "message": "Query validation failed: ...", "session_id": "..." }

{
  "messages": [
    { "role": "user", "content": "Summarize the key findings from the report" }
  ],
  "s3_report_url": "https://qubitz-research-reports.s3.amazonaws.com/.../report.md",
  "user_id": "user123",
  "session_id": "session456",
  "project_id": "project21"
}

{ "type": "chat_status", "message": "Processing chat request...", "session_id": "..." }

{ "type": "chat_chunk", "chunk": "The report highlights three key...", "is_final": false, "session_id": "..." }

{
  "type": "chat_complete",
  "success": true,
  "response": {
    "metadata": {
      "tools_used": {
        "web_search": ["query1", "query2"],
        "report_generated": { "success": false }
      }
    },
    "token_usage": {
      "input_tokens": 15000,
      "output_tokens": 2000,
      "total_tokens": 17000
    }
  },
  "session_info": {
    "user_id": "user123",
    "session_id": "session456",
    "message_count": 3,
    "token_usage": {
      "input_tokens": 15000,
      "output_tokens": 2000,
      "total_tokens": 17000,
      "limit": 250000,
      "limit_reached": false
    }
  }
}

{ "type": "chat_error", "error": "TOKEN_LIMIT_EXCEEDED", "message": "...", "session_id": "..." }

{
  "user_id": "user123",
  "project_id": "project21",
  "use_case_name": "Automated Financial Research Platform",
  "use_case_description": "Investment firms conducting market research face challenges with information accuracy and research scalability.",
  "s3_uri": "https://qubitz-research-reports.s3.amazonaws.com/.../report.md"
}

{
  "type": "ack",
  "data": { "user_id": "user123", "session_id": "...", "project_id": "project21", "action": "generate", "status": "processing" }
}

{ "type": "stream_start", "data": { "message": "Generating architecture specification...", "model": "claude-sonnet-4-5-20250929" } }

{ "type": "stream_chunk", "data": { "chunk": "Based on the use case...", "chunk_index": 0 } }

{ "type": "stream_end", "data": { "total_chunks": 42, "completion_time": 8.5 } }

{
  "type": "architecture",
  "data": {
    "user_id": "user123",
    "project_id": "project21",
    "architecture": {
      "agents_config": {
        "research_agent": {
          "name": "Research Agent",
          "description": "Conducts market research and data gathering",
          "model": "anthropic.claude-sonnet-4-5-20250929-v1:0",
          "prompt": "You are a research agent...",
          "tools": ["web_search", "document_reader"],
          "memory": { "enabled": true, "strategies": ["summary"] }
        },
        "analysis_agent": {
          "name": "Analysis Agent",
          "description": "Analyzes gathered data...",
          "model": "anthropic.claude-sonnet-4-5-20250929-v1:0",
          "prompt": "You are an analysis agent...",
          "tools": ["calculator", "data_viz"],
          "memory": { "enabled": true, "strategies": ["summary"] }
        }
      },
      "gateway_config": { "provider": "api_gateway", "targets": [] }
    },
    "status": "pending"
  }
}

{ "type": "keepalive", "data": { "message": "Processing in progress... (15s)", "elapsed_seconds": 15 } }

{ "type": "error", "data": { "error": "generation_failed", "message": "..." } }

{
  "user_id": "user123",
  "project_id": "project21",
  "user_input": "Add a security agent that validates all API calls and enforces rate limiting"
}

{
  "user_id": "user123",
  "project_id": "project21"
}

{
  "type": "deployment_started",
  "data": {
    "status": "started",
    "message": "Deployment started. Generating infrastructure and pushing to GitHub...",
    "user_id": "user123",
    "project_id": "project21"
  }
}

{
  "type": "deployment_complete",
  "data": {
    "status": "success",
    "deployment_status": "deploying_via_cicd",
    "message": "Code pushed to Qubitz-202/my-app. GitHub Actions is deploying via CDK.",
    "github_repo": "https://github.com/Qubitz-202/my-app",
    "user_id": "user123",
    "project_id": "project21"
  }
}

{ "type": "status", "data": { "status": "deploying", "message": "Deploy CDK - Deploy with CDK", "progress_percent": 65 } }

{
  "type": "deployment_complete",
  "data": {
    "status": "deployed",
    "deployment_status": "deployed",
    "message": "Deployment successful!",
    "agent_endpoint": "https://api.qubitz.ai/my_app/invoke",
    "github_repo": "https://github.com/Qubitz-202/my-app",
    "user_id": "user123",
    "project_id": "project21"
  }
}

{ "type": "complete" }

{ "type": "error", "data": { "error": "no_architecture", "message": "No architecture spec found. Generate one first with /getspec." } }

{
  "user_id": "user123",
  "project_id": "project21",
  "key_name": "production-key"
}

{
  "type": "api_key_created",
  "data": {
    "api_key_value": "aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
    "api_key_id": "abc123def",
    "usage_plan_id": "plan456",
    "api_endpoint": "https://api.qubitz.ai/my_app/invoke"
  }
}

{
  "user_id": "user123",
  "project_id": "project21",
  "api_key_id": "abc123def",
  "usage_plan_id": "plan456"
}

{
  "type": "api_key_deleted",
  "data": { "api_key_id": "abc123def" }
}

type QubitzMessage = {
  type: string;
  data?: Record<string, any>;
  message?: string;
  chunk?: string;
  [key: string]: any;
};

function connectQubitz(
  endpoint: string,
  apiKey: string,
  payload: Record<string, any>,
  handlers: {
    onMessage?: (msg: QubitzMessage) => void;
    onChunk?: (text: string) => void;
    onComplete?: (msg: QubitzMessage) => void;
    onError?: (msg: QubitzMessage) => void;
    onProgress?: (percent: number, message: string) => void;
  }
): WebSocket {
  const ws = new WebSocket(
    `wss://api.qubitz.ai/${endpoint}?api_key=${apiKey}`
  );

  ws.onopen = () => {
    ws.send(JSON.stringify(payload));
  };

  ws.onmessage = (event) => {
    const msg: QubitzMessage = JSON.parse(event.data);
    handlers.onMessage?.(msg);

    switch (msg.type) {
      // Research chunks
      case "stream_chunk":
        handlers.onChunk?.(msg.data?.chunk ?? "");
        break;

      // Chat chunks
      case "chat_chunk":
        handlers.onChunk?.(msg.chunk ?? "");
        break;

      // Spec generation chunks
      case "claude_chunk":
        handlers.onChunk?.(msg.chunk ?? "");
        break;

      // Deploy progress
      case "status":
        if (msg.data?.progress_percent !== undefined) {
          handlers.onProgress?.(msg.data.progress_percent, msg.data.message);
        }
        break;

      // Completion types
      case "complete":
      case "chat_complete":
      case "deployment_complete":
      case "architecture":
      case "use_cases_complete":
      case "api_key_created":
      case "api_key_deleted":
        handlers.onComplete?.(msg);
        break;

      // Errors
      case "error":
      case "chat_error":
        handlers.onError?.(msg);
        break;
    }
  };

  ws.onerror = (err) => {
    handlers.onError?.({ type: "error", message: "WebSocket error" });
  };

  return ws;
}

const ws = connectQubitz("research", "qk_uct_...", {
  prompt: "Latest AI Trends 2026",
  company_name: "TestCompany",
  company_url: "https://example.com/",
  user_id: "user123",
  session_id: "session456",
}, {
  onChunk: (text) => process.stdout.write(text),
  onComplete: (msg) => {
    if (msg.type === "use_cases_complete") {
      console.log(`\n${msg.use_cases.length} use cases generated`);
    }
    if (msg.type === "complete") {
      console.log("\nReport URLs:", msg.all_s3_urls);
      ws.close();
    }
  },
  onError: (msg) => console.error("Error:", msg.message),
});

let response = "";

const ws = connectQubitz("chat", "qk_uct_...", {
  messages: [{ role: "user", content: "What are the key findings?" }],
  s3_report_url: "https://qubitz-research-reports.s3.amazonaws.com/.../report.md",
  user_id: "user123",
  session_id: "session456",
  project_id: "project21",
}, {
  onChunk: (text) => { response += text; },
  onComplete: (msg) => {
    if (msg.type === "chat_complete") {
      console.log("Full response:", response);
      console.log("Tokens used:", msg.response.token_usage.total_tokens);
      ws.close();
    }
  },
});

// Step 1: Generate architecture spec
const specWs = connectQubitz("getspec", "qk_ch_...", {
  user_id: "user123",
  project_id: "project21",
  use_case_name: "Financial Research Platform",
  use_case_description: "AI-powered investment research...",
  s3_uri: "https://qubitz-research-reports.s3.amazonaws.com/.../report.md",
}, {
  onComplete: (msg) => {
    if (msg.type === "architecture") {
      console.log("Agents:", Object.keys(msg.data.architecture.agents_config));
      specWs.close();
      deployApp(); // proceed to deploy
    }
  },
});

// Step 2: Deploy
function deployApp() {
  const deployWs = connectQubitz("deploy", "qk_ch_...", {
    user_id: "user123",
    project_id: "project21",
  }, {
    onProgress: (pct, msg) => console.log(`[${pct}%] ${msg}`),
    onComplete: (msg) => {
      if (msg.type === "deployment_complete" && msg.data?.deployment_status === "deployed") {
        console.log("Live at:", msg.data.agent_endpoint);
        deployWs.close();
      }
    },
  });
}

import asyncio
import json
import websockets


async def connect_qubitz(endpoint: str, api_key: str, payload: dict):
    """Connect to a Qubitz WebSocket endpoint and yield messages."""
    url = f"wss://api.qubitz.ai/{endpoint}?api_key={api_key}"

    async with websockets.connect(
        url,
        ping_interval=30,
        ping_timeout=300,
        close_timeout=60,
    ) as ws:
        await ws.send(json.dumps(payload))

        async for raw in ws:
            msg = json.loads(raw)
            yield msg

            if msg.get("type") in ("complete", "error", "chat_error"):
                break

async def run_research():
    async for msg in connect_qubitz("research", "qk_uct_...", {
        "prompt": "Latest AI Trends 2026",
        "company_name": "TestCompany",
        "company_url": "https://example.com/",
        "user_id": "user123",
        "session_id": "session456",
    }):
        match msg["type"]:
            case "status" | "multiagent_step":
                print(f"[{msg['type']}] {msg.get('message', '')}")
            case "s3_upload_complete":
                print(f"Uploaded: {msg['s3_url']}")
            case "use_cases_complete":
                for uc in msg["use_cases"]:
                    print(f"  - {uc['title']} ({uc['impact_score']})")
            case "complete":
                print(f"\nReport: {msg['s3_deep_research_report_url']}")
                print(f"PDF:    {msg['s3_deep_research_pdf_url']}")
            case "error":
                print(f"ERROR: {msg.get('message')}")

asyncio.run(run_research())

async def chat_with_report():
    full_response = ""

    async for msg in connect_qubitz("chat", "qk_uct_...", {
        "messages": [{"role": "user", "content": "Summarize the key findings"}],
        "s3_report_url": "https://qubitz-research-reports.s3.amazonaws.com/.../report.md",
        "user_id": "user123",
        "session_id": "session456",
        "project_id": "project21",
    }):
        match msg["type"]:
            case "chat_chunk":
                full_response += msg.get("chunk", "")
                print(msg.get("chunk", ""), end="", flush=True)
            case "chat_complete":
                tokens = msg["response"]["token_usage"]["total_tokens"]
                print(f"\n\n--- {tokens} tokens used ---")

asyncio.run(chat_with_report())

async def generate_and_deploy():
    # Step 1: Generate spec
    print("Generating architecture spec...")
    async for msg in connect_qubitz("getspec", "qk_ch_...", {
        "user_id": "user123",
        "project_id": "project21",
        "use_case_name": "Financial Research Platform",
        "use_case_description": "AI-powered investment research...",
        "s3_uri": "https://qubitz-research-reports.s3.amazonaws.com/.../report.md",
    }):
        if msg["type"] == "architecture":
            agents = msg["data"]["architecture"]["agents_config"]
            print(f"Generated {len(agents)} agents: {list(agents.keys())}")
            break

    # Step 2: Deploy
    print("\nDeploying...")
    async for msg in connect_qubitz("deploy", "qk_ch_...", {
        "user_id": "user123",
        "project_id": "project21",
    }):
        match msg["type"]:
            case "status" if "progress_percent" in msg.get("data", {}):
                print(f"  [{msg['data']['progress_percent']}%] {msg['data']['message']}")
            case "deployment_complete":
                data = msg["data"]
                if data.get("deployment_status") == "deployed":
                    print(f"\nLive at: {data['agent_endpoint']}")
                    print(f"GitHub:  {data['github_repo']}")

    # Step 3: Create API key for the deployed app
    print("\nCreating API key...")
    async for msg in connect_qubitz("createapikey", "qk_ch_...", {
        "user_id": "user123",
        "project_id": "project21",
        "key_name": "production-key",
    }):
        if msg["type"] == "api_key_created":
            data = msg["data"]
            print(f"API Key:  {data['api_key_value']}")
            print(f"Key ID:   {data['api_key_id']}")
            print(f"Endpoint: {data['api_endpoint']}")

asyncio.run(generate_and_deploy())

{ "type": "error", "message": "No architecture spec found. Generate one first with /getspec." }