{"openapi":"3.1.0","info":{"title":"Unseen Workflow Compiler API","description":"Create workflow visuals from supplied business evidence, with source references and editable output.","version":"1.0.0"},"servers":[{"url":"https://unseendocs.in","description":"Unseen Production Gateway"}],"paths":{"/api/compile-spec":{"post":{"operationId":"compileVisualSpec","summary":"Compile a Host-LLM VisualSpec v0.1 JSON into clean orthogonal SVG, Mermaid, Excalidraw, and interactive Studio link ($0 credits, Bearer auth required)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["spec"],"properties":{"orientation":{"type":"string","enum":["portrait","landscape"]},"swimlane":{"type":"boolean","description":"Auto-groups steps into actor swimlanes when >= 2 actors exist"},"spec":{"type":"object","required":["schemaVersion","kind","title","sources","nodes","edges"],"properties":{"schemaVersion":{"type":"string","enum":["0.1"],"default":"0.1"},"kind":{"type":"string","enum":["flowchart"],"default":"flowchart"},"title":{"type":"string","maxLength":100},"summary":{"type":"string","maxLength":400},"sources":{"type":"array","items":{"type":"object","required":["id","locator","excerpt"],"properties":{"id":{"type":"string"},"locator":{"type":"string"},"excerpt":{"type":"string"}}}},"nodes":{"type":"array","items":{"type":"object","required":["id","label","role","sourceIds"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"role":{"type":"string","enum":["step","decision","concept"]},"actor":{"type":"string"},"detail":{"type":"string"},"sourceIds":{"type":"array","items":{"type":"string"}}}}},"edges":{"type":"array","items":{"type":"object","required":["from","to","sourceIds"],"properties":{"from":{"type":"string"},"to":{"type":"string"},"label":{"type":"string","description":"Required for outgoing branches of decision nodes"},"sourceIds":{"type":"array","items":{"type":"string"}}}}}}}}}}}},"responses":{"200":{"description":"Compiled SVG, Mermaid, Excalidraw scene, and interactive studioUrl ($0 creditsCharged)"},"400":{"description":"Contract or citation validation error list (`missingAreas`) for 1-turn self-correction"}}}},"/api/generate":{"post":{"operationId":"generateVisual","summary":"Generate VisualSpec from extracted source chunks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sources"],"properties":{"kind":{"type":"string","enum":["flowchart","infographic"],"default":"flowchart"},"sources":{"type":"array","items":{"type":"object","required":["id","locator","excerpt"],"properties":{"id":{"type":"string"},"locator":{"type":"string"},"excerpt":{"type":"string"},"discourseRole":{"type":"string","enum":["procedural","context","boilerplate"]}}}}}}}}},"responses":{"200":{"description":"Validated VisualSpec with metadata"}}}},"/api/classify-discourse":{"post":{"operationId":"classifyDiscourse","summary":"Classify source chunks into procedural steps vs. background context vs. boilerplate","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sources"],"properties":{"sources":{"type":"array","items":{"type":"object","required":["id","locator","excerpt"],"properties":{"id":{"type":"string"},"locator":{"type":"string"},"excerpt":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Array of classified sources with discourseRole and discourseScore"}}}},"/api/auth/otp/request":{"post":{"operationId":"requestLoginOtp","summary":"Request 6-digit Login OTP for Agent & Human Sign-In (Email + OTP)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"6-digit Login OTP dispatched to email (`UNSEEN_LOGIN_OTP`)"}}}},"/api/auth/otp/verify":{"post":{"operationId":"verifyLoginOtp","summary":"Verify 6-digit Login OTP and obtain Bearer session token (`utok_...`)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","otp"],"properties":{"email":{"type":"string","format":"email"},"otp":{"type":"string","description":"6-digit login code"}}}}}},"responses":{"200":{"description":"Session Bearer token (`utok_...`) and user profile"}}}},"/api/auth/login":{"post":{"operationId":"loginWithPassword","summary":"Sign in with Email + Password and obtain Bearer session token (`utok_...`)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Session Bearer token (`utok_...`) and user profile"}}}},"/api/enhance":{"post":{"operationId":"enhanceVisual","summary":"Bundled AI Enhance (TypeSafe Jev semantic verification and missing branch repair)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["spec","visualId"],"properties":{"spec":{"type":"object"},"visualId":{"type":"string"}}}}}},"responses":{"200":{"description":"Enhanced VisualSpec and Jev quality metrics"}}}},"/api/detect-workflows":{"post":{"operationId":"detectWorkflows","summary":"Discover candidate workflows from multi-section document sources","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sources"],"properties":{"sources":{"type":"array","items":{"type":"object","required":["id","locator","excerpt"],"properties":{"id":{"type":"string"},"locator":{"type":"string"},"excerpt":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Candidate workflows with sourceIds and Jev audit"}}}},"/api/extract/text":{"post":{"operationId":"extractPastedText","summary":"Segment raw operational prose into cited Source[] chunks with locators","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string"}}}}}},"responses":{"200":{"description":"Segmented sources[] array ready for compile_workflow or /api/generate"}}}},"/api/extract/file":{"post":{"operationId":"extractDocumentFile","summary":"Extract verbatim Source[] chunks with page/section/row locators from PDF, DOCX, PPTX, XLSX, CSV, MD, or TXT","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fileBase64"],"properties":{"fileBase64":{"type":"string","description":"Base64-encoded binary document payload (<= 5 MB)"},"filename":{"type":"string","description":"Original filename with extension (e.g. 'sop.pdf', 'playbook.docx', 'triage.xlsx')"},"mimetype":{"type":"string","description":"MIME type (e.g. 'application/pdf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')"},"sheet":{"type":"string","description":"Optional worksheet name for multi-sheet XLSX workbooks"}}}}}},"responses":{"200":{"description":"Extracted sources[] array with locators and pageCount"}}}},"/api/extract/sheets":{"post":{"operationId":"listSpreadsheetSheets","summary":"List worksheet tab names in an uploaded XLSX workbook before extraction","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fileBase64"],"properties":{"fileBase64":{"type":"string","description":"Base64-encoded XLSX workbook"}}}}}},"responses":{"200":{"description":"Array of worksheet tab names (`sheets: string[]`)"}}}},"/mcp":{"post":{"operationId":"mcpRpc","summary":"Model Context Protocol JSON-RPC 2.0 Dispatcher (compile_workflow, revise_workflow, autofix_workflow, enhance_workflow, detect_workflows, get_workflow, get_account_status, auth_request_otp, auth_verify_otp, auth_login, send_feedback)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response frame"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Token","description":"Unseen Account API Key or Session Bearer Token"}}},"security":[{"bearerAuth":[]}]}