{"openapi":"3.1.0","info":{"title":"DemoAgent API","description":"AI-powered interactive product demo API by iraa.ai. Start live demos, capture leads, generate shareable links, and run headless demo conversations.","version":"0.1.0","contact":{"name":"iraa.ai","url":"https://iraa.ai","email":"hello@iraa.ai"},"x-logo":{"url":"https://iraa.ai/logo.png"}},"servers":[{"url":"https://api.iraa.ai","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/session":{"post":{"operationId":"createDemoSession","summary":"Start a new demo session","description":"Create a new AI-guided demo session for a product. Returns a session ID, auth token, and the agent's initial greeting. Use the token for subsequent chat calls.","tags":["Sessions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string","format":"uuid","description":"The product to demo"},"visitorMeta":{"type":"object","description":"Optional visitor context (name, email, company, needs)","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"company":{"type":"string"},"needs":{"type":"array","items":{"type":"string"},"description":"Pre-discovered visitor needs"},"persona":{"type":"string","description":"Pre-matched persona ID"}}}}}}}},"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"token":{"type":"string","description":"JWT for session auth"},"greeting":{"type":"object","nullable":true,"properties":{"text":{"type":"string"},"speech":{"type":"string"},"suggestions":{"type":"array","items":{"type":"string"}}}},"agent":{"type":"object","properties":{"name":{"type":"string"},"tone":{"type":"string"}}}}}}}}}}},"/api/v1/session/{sessionId}/chat":{"post":{"operationId":"sendDemoMessage","summary":"Send a message to a demo session","description":"Send a visitor message and receive the AI agent's response including text, suggestions, and iframe commands for the demo UI.","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"The message to send"}}}}}},"responses":{"200":{"description":"Agent response","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"Markdown text response"},"speech":{"type":"string","description":"Plain text for TTS"},"suggestions":{"type":"array","items":{"type":"string"}},"iframeCommands":{"type":"array","items":{"type":"object"},"description":"UI commands for the demo (navigate, click, fill, highlight)"},"agentId":{"type":"string"},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"}}}}}}}}}}},"/api/v1/session/{sessionId}/lead":{"post":{"operationId":"captureLead","summary":"Capture lead information","description":"Record lead data (email, name, company, phone) for an active session.","tags":["Leads"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"company":{"type":"string"},"phone":{"type":"string"}}}}}},"responses":{"200":{"description":"Lead captured","content":{"application/json":{"schema":{"type":"object","properties":{"leadId":{"type":"string","format":"uuid"},"captured":{"type":"boolean"}}}}}}}}},"/api/v1/session/{sessionId}/end":{"post":{"operationId":"endDemoSession","summary":"End a demo session","tags":["Sessions"],"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Session ended","content":{"application/json":{"schema":{"type":"object","properties":{"ended":{"type":"boolean"}}}}}}}}},"/api/v1/partner/demo-link":{"post":{"operationId":"createDemoLink","summary":"Generate a pre-seeded demo link","description":"Create a unique demo URL pre-loaded with visitor context (name, needs, persona, flow). The visitor clicks the link and immediately enters a personalized demo — no discovery phase. Single-use with configurable expiry. Requires secret key (sk_live_*).","tags":["Partner"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string","format":"uuid"},"visitorContext":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"company":{"type":"string"},"needs":{"type":"array","items":{"type":"string"}},"persona":{"type":"string"},"referringAgent":{"type":"string","description":"Name of the agent that generated this link"}}},"options":{"type":"object","properties":{"flow":{"type":"string","description":"Pre-select a demo flow by ID"},"expiresIn":{"type":"integer","description":"Link expiry in seconds (default: 86400)"},"redirectOnComplete":{"type":"string","format":"uri","description":"URL to redirect after demo ends"},"webhookUrl":{"type":"string","format":"uri","description":"URL to POST session results"}}}}}}}},"responses":{"200":{"description":"Demo link created","content":{"application/json":{"schema":{"type":"object","properties":{"linkId":{"type":"string","format":"uuid"},"demoUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}}},"/api/v1/partner/headless":{"post":{"operationId":"runHeadlessDemo","summary":"Run a headless demo session","description":"Execute a complete demo conversation programmatically — no browser, no UI. Send up to 20 messages and receive the full transcript, lead signals, features shown, and token usage. Perfect for other AI agents that need to demo a product without a visual interface.","tags":["Partner"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId","messages"],"properties":{"productId":{"type":"string","format":"uuid"},"messages":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Visitor messages to send sequentially"},"visitorContext":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"company":{"type":"string"},"needs":{"type":"array","items":{"type":"string"}},"persona":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Headless demo result","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid"},"transcript":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["visitor","agent"]},"content":{"type":"string"},"agentId":{"type":"string"}}}},"summary":{"type":"object","properties":{"featuresShown":{"type":"array","items":{"type":"string"}},"discoveredNeeds":{"type":"array","items":{"type":"string"}},"matchedPersona":{"type":"string","nullable":true},"leadCaptured":{"type":"boolean"}}},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"},"messageCount":{"type":"integer"}}}}}}}}}}},"/api/v1/partner/embed":{"post":{"operationId":"getEmbedSnippet","summary":"Get an iframe embed snippet","description":"Returns an HTML iframe snippet with a pre-seeded demo URL.","tags":["Partner"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["productId"],"properties":{"productId":{"type":"string","format":"uuid"},"visitorContext":{"type":"object"},"embedOptions":{"type":"object","properties":{"width":{"type":"string","default":"100%"},"height":{"type":"string","default":"700px"},"theme":{"type":"string","enum":["light","dark"],"default":"light"}}}}}}}},"responses":{"200":{"description":"Embed snippet","content":{"application/json":{"schema":{"type":"object","properties":{"embedUrl":{"type":"string","format":"uri"},"embedHtml":{"type":"string"}}}}}}}}},"/mcp":{"post":{"operationId":"mcpRequest","summary":"MCP JSON-RPC endpoint","description":"Model Context Protocol (MCP) endpoint for Claude and other MCP-compatible agents. Accepts JSON-RPC 2.0 requests. Supports methods: initialize, tools/list, tools/call, resources/list, resources/read.","tags":["MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string","enum":["initialize","tools/list","tools/call","resources/list","resources/read"]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"MCP JSON-RPC response","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Use a public key (pk_live_*) for session endpoints or a secret key (sk_live_*) for partner/admin endpoints. Get keys at https://iraa.ai/dashboard/keys"}}},"tags":[{"name":"Sessions","description":"Create and manage interactive demo sessions"},{"name":"Leads","description":"Capture visitor lead information during demos"},{"name":"Partner","description":"Partner API for programmatic demo creation, embedding, and headless execution"},{"name":"MCP","description":"Model Context Protocol endpoint for AI agent integration"}]}