{"openapi":"3.1.0","info":{"title":"Flowtivity API","version":"1.0.0","description":"Flowtivity helps businesses redesign how work gets done with AI. This API provides access to website scanning, automation opportunity analysis, AI readiness scoring, AEO (AI Engine Optimization) scoring, the AI Business Directory, webhooks, and analytics. Free tier: 3 scans/day without authentication.","contact":{"name":"Flowtivity Support","email":"aj@flowtivityconsulting.com","url":"https://flowtivity.ai/contact/"},"termsOfService":"https://flowtivity.ai/terms/","x-logo":{"url":"https://flowtivity.ai/assets/og-image-v2.png"}},"servers":[{"url":"https://flowtivity.ai","description":"Production server"}],"security":[{},{"ApiKeyAuth":[]}],"paths":{"/api/health":{"get":{"operationId":"getHealth","summary":"Health check and API discovery","description":"Free unauthenticated endpoint returning API status, capabilities, and quickstart guide. Use this to verify connectivity before making other calls.","tags":["Meta"],"responses":{"200":{"description":"API health status with capability discovery","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"Overall API health"},"service":{"type":"string","example":"Flowtivity API"},"version":{"type":"string","example":"1.0.0"},"timestamp":{"type":"string","format":"date-time"},"response_time_ms":{"type":"number","description":"Server response time in milliseconds"},"capabilities":{"type":"object","properties":{"free_tier":{"type":"boolean"},"scan_types":{"type":"array","items":{"type":"string"}},"free_scan_limit":{"type":"string"}}}}}}}}}}},"/api/insights/scan":{"post":{"operationId":"triggerScan","summary":"Trigger a new website scan","description":"Initiate a business insight scan for a website. Analyzes automation readiness, AI opportunities, workflows, and AEO score. Free tier: 3 scans/day without API key. Returns the scan ID for tracking progress.","tags":["Scanning"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Website URL to scan (domain or full URL)","examples":["example.com","https://mystore.com"]},"email":{"type":"string","format":"email","description":"Optional email to receive scan report when complete"},"scanType":{"type":"string","enum":["light","basic","full"],"description":"Scan depth: light (1 agent, ~30s), basic (4 agents, ~2min), full (12 agents, ~5min). Default: basic"}},"required":["url"],"additionalProperties":false}}}},"responses":{"200":{"description":"Scan initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"scanId":{"type":"string","format":"uuid","description":"Unique scan identifier for tracking"},"status":{"type":"string","enum":["pending","fetching"],"description":"Initial scan status"},"message":{"type":"string","description":"Human-readable status message"}},"required":["scanId","status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/insights/scan/{scanId}/status":{"get":{"operationId":"getScanStatus","summary":"Check scan status and progress","description":"Poll this endpoint to track scan progress. Returns current status and percentage. Poll every 5-10 seconds until status is 'complete' or 'error'.","tags":["Scanning"],"parameters":[{"name":"scanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID returned by triggerScan"}],"responses":{"200":{"description":"Current scan status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","fetching","analyzing","complete","error"],"description":"Current processing stage"},"progress":{"type":"number","minimum":0,"maximum":100,"description":"Estimated completion percentage"},"error":{"type":"string","nullable":true,"description":"Error message if status is 'error'"}},"required":["status","progress"]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/insights/scan/{scanId}/results":{"get":{"operationId":"getScanResults","summary":"Get full scan results","description":"Retrieve complete analysis results. Call after status is 'complete'. Includes organization structure, workflows, automation opportunities, readiness score, AEO score, and key findings.","tags":["Scanning"],"parameters":[{"name":"scanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID returned by triggerScan"}],"responses":{"200":{"description":"Complete scan results with scores, workflows, and opportunities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResults"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/insights/scan/{scanId}/comprehensive":{"get":{"operationId":"getComprehensiveScan","summary":"Get comprehensive scan with playbook and directory listing","description":"Full scan results plus AI automation playbook, AEO boost recommendations, and AI Business Directory listing. All related data in one call.","tags":["Scanning"],"parameters":[{"name":"scanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID returned by triggerScan"}],"responses":{"200":{"description":"Comprehensive scan results with playbook and directory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComprehensiveScanResults"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/insights/scans":{"get":{"operationId":"listScans","summary":"List recent scans with pagination","description":"List scans ordered by creation date (newest first). Supports filtering by status or domain, and cursor-based pagination.","tags":["Scanning"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Maximum number of results"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","fetching","analyzing","complete","error"]},"description":"Filter by scan status"},{"name":"domain","in":"query","schema":{"type":"string"},"description":"Filter by domain (partial match)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from previous response"},{"name":"include_results","in":"query","schema":{"type":"boolean","default":false},"description":"Include full results with each scan"}],"responses":{"200":{"description":"Paginated list of scans","content":{"application/json":{"schema":{"type":"object","properties":{"scans":{"type":"array","items":{"$ref":"#/components/schemas/ScanSummary"}},"total":{"type":"integer","description":"Total matching scans"},"hasMore":{"type":"boolean","description":"Whether more results exist"},"nextCursor":{"type":"string","nullable":true,"description":"Cursor for next page"}},"required":["scans","total","hasMore"]}}}}}}},"/api/insights/playbook/{scanId}":{"get":{"operationId":"getPlaybook","summary":"Get AI automation playbook","description":"Get the tailored AI automation playbook for a completed scan. Includes skills library, 90-day implementation roadmap, tool recommendations, and priority rankings.","tags":["Analysis"],"parameters":[{"name":"scanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID of a completed scan"},{"name":"include_skills","in":"query","schema":{"type":"boolean","default":true},"description":"Include full AI skills library"}],"responses":{"200":{"description":"AI automation playbook with roadmap and skills","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"scanId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["generating","complete"]},"skillCount":{"type":"number","description":"Number of AI skills identified"},"topPrioritySkills":{"type":"array","items":{"type":"string"}},"roadmap":{"type":"object"},"skills":{"type":"array","items":{"type":"object"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/directory":{"get":{"operationId":"listDirectory","summary":"Browse the AI Business Directory","description":"List businesses in the AI Business Directory. Filter by industry and paginate through results. Each listing includes automation scores and key insights.","tags":["Directory"],"parameters":[{"name":"industry","in":"query","schema":{"type":"string","enum":["technology","healthcare","finance","retail","professional-services","education","manufacturing","real-estate","marketing","consulting","other"]},"description":"Filter by industry vertical"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":50},"description":"Max results per page"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Offset for pagination"}],"responses":{"200":{"description":"Directory listings","content":{"application/json":{"schema":{"type":"object","properties":{"listings":{"type":"array","items":{"$ref":"#/components/schemas/DirectoryListing"}},"total":{"type":"integer"}},"required":["listings","total"]}}}}}}},"/api/directory/{slug}":{"get":{"operationId":"getDirectoryListing","summary":"Get a specific directory listing","description":"Get detailed AI Business Directory listing by its URL slug. Includes full automation analysis, scores, and recommendations.","tags":["Directory"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Directory listing slug (e.g. 'example-com')"}],"responses":{"200":{"description":"Directory listing details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryListing"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/insights/analytics":{"get":{"operationId":"getAnalyticsSummary","summary":"Get aggregate analytics","description":"Aggregate analytics across all scans: total count, average scores, top opportunities, common workflows. Useful for dashboards and trend analysis.","tags":["Analytics"],"parameters":[{"name":"time_range","in":"query","schema":{"type":"string","enum":["7d","30d","90d","all"],"default":"30d"},"description":"Time window for aggregation"}],"responses":{"200":{"description":"Analytics summary","content":{"application/json":{"schema":{"type":"object","properties":{"totalScans":{"type":"integer"},"averageReadinessScore":{"type":"number"},"averageAeoScore":{"type":"number"},"topOpportunityCategories":{"type":"array","items":{"type":"string"}},"scansByStatus":{"type":"object","additionalProperties":{"type":"integer"}}}}}}}}}},"/api/insights/search":{"get":{"operationId":"searchInsights","summary":"Search across all scans","description":"Full-text search across all scan results, opportunities, and workflows. Returns matching items ranked by relevance.","tags":["Analysis"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Search query string"},{"name":"search_type","in":"query","schema":{"type":"string","enum":["all","opportunities","workflows","domains"],"default":"all"},"description":"Scope of search"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50},"description":"Max results"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"query":{"type":"string"}},"required":["results","total","query"]}}}}}}},"/api/webhooks/subscribe":{"get":{"operationId":"getWebhookDocs","summary":"Get webhook documentation","description":"List supported webhook events, subscription format, and delivery details.","tags":["Webhooks"],"responses":{"200":{"description":"Webhook documentation and supported events"}}},"post":{"operationId":"subscribeWebhook","summary":"Subscribe to webhook events","description":"Register a callback URL to receive real-time event notifications when scans complete, fail, or directory listings update.","tags":["Webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callback_url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook POST requests"},"events":{"type":"array","items":{"type":"string","enum":["scan.completed","scan.failed","scan.started","directory.updated","insights.updated","analytics.weekly"]},"description":"Event types to subscribe to"},"secret":{"type":"string","description":"Optional HMAC secret for signature verification"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional metadata attached to the subscription"}},"required":["callback_url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"Webhook subscription created","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"subscription":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["active"]},"callback_url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-mcp-api-key","description":"API key for higher rate limits and authenticated access. Free tier available without key."},"BearerAuth":{"type":"http","scheme":"bearer","description":"OAuth 2.0 Bearer token from Clerk authentication"}},"schemas":{"ScanSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique scan identifier"},"domain":{"type":"string","description":"Scanned domain"},"url":{"type":"string","format":"uri","description":"Full URL that was scanned"},"email":{"type":"string","format":"email","description":"Email associated with scan"},"status":{"type":"string","enum":["pending","fetching","analyzing","complete","error"],"description":"Current scan status"},"createdAt":{"type":"number","description":"Unix timestamp when scan was created"},"completedAt":{"type":"number","nullable":true,"description":"Unix timestamp when scan completed"},"errorMessage":{"type":"string","nullable":true,"description":"Error message if status is 'error'"}},"required":["id","domain","status","createdAt"]},"ScoreBreakdown":{"type":"object","properties":{"category":{"type":"string","description":"Score category name"},"score":{"type":"number","minimum":0,"maximum":100,"description":"Score for this category"},"explanation":{"type":"string","description":"Why this score was given"}},"required":["category","score","explanation"]},"Opportunity":{"type":"object","properties":{"id":{"type":"string","description":"Unique opportunity identifier"},"title":{"type":"string","description":"Short descriptive title"},"description":{"type":"string","description":"Detailed description of the opportunity"},"currentState":{"type":"string","description":"How the process currently works"},"potentialState":{"type":"string","description":"How it could work with automation"},"impact":{"type":"string","enum":["high","medium","low"],"description":"Business impact level"},"effort":{"type":"string","enum":["high","medium","low"],"description":"Implementation effort level"},"category":{"type":"string","description":"Opportunity category (e.g. 'workflow', 'communication', 'data')"},"estimatedTimeSavingsHours":{"type":"number","description":"Estimated hours saved per month"},"estimatedTimeSavingsRange":{"type":"string","description":"Human-readable savings range (e.g. '10-20 hrs/month')"},"automationApproach":{"type":"array","items":{"type":"string"},"description":"Suggested automation technologies"},"priority":{"type":"number","description":"Priority ranking (lower = higher priority)"},"recommendedTools":{"type":"array","items":{"type":"string"},"description":"Specific tools recommended"}},"required":["id","title","description","impact","effort","category"]},"Workflow":{"type":"object","properties":{"name":{"type":"string","description":"Workflow name"},"description":{"type":"string","description":"What this workflow accomplishes"},"steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Step name"},"description":{"type":"string","description":"What happens in this step"},"isManual":{"type":"boolean","description":"Whether this step requires manual human action"}},"required":["name","isManual"]},"description":"Ordered list of steps in the workflow"},"isDeterministic":{"type":"boolean","description":"Whether the workflow follows a fixed sequence"},"automationPotential":{"type":"string","enum":["high","medium","low"],"description":"How automatable this workflow is"},"currentState":{"type":"string","description":"Current workflow implementation"}},"required":["name","description","automationPotential"]},"DirectoryListing":{"type":"object","properties":{"businessName":{"type":"string","description":"Business name"},"slug":{"type":"string","description":"URL-safe slug"},"domain":{"type":"string","description":"Business website domain"},"industry":{"type":"string","description":"Industry vertical"},"readinessScore":{"type":"number","description":"AI readiness score (0-100)"},"aeoScore":{"type":"number","description":"AEO score (0-100)"},"description":{"type":"string","description":"Business description"}},"required":["businessName","slug"]},"ScanResults":{"type":"object","properties":{"scan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"number"},"completedAt":{"type":"number","nullable":true}},"required":["id","domain","status"]},"results":{"type":"object","properties":{"scanId":{"type":"string","format":"uuid"},"domain":{"type":"string"},"readinessScore":{"type":"number","minimum":0,"maximum":100,"description":"Overall AI readiness score"},"aeoScore":{"type":"number","minimum":0,"maximum":100,"description":"AI Engine Optimization score"},"readinessBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/ScoreBreakdown"}},"aeoBreakdown":{"type":"array","items":{"$ref":"#/components/schemas/ScoreBreakdown"}},"executiveSummary":{"type":"string","description":"High-level summary of findings"},"keyFindings":{"type":"array","items":{"type":"string"},"description":"Top findings from the analysis"},"totalTimeSavingsPotential":{"type":"string","description":"Estimated monthly time savings"},"workflows":{"type":"array","items":{"$ref":"#/components/schemas/Workflow"}},"opportunities":{"type":"array","items":{"$ref":"#/components/schemas/Opportunity"}}},"required":["scanId","domain","readinessScore","aeoScore"]}},"required":["scan"]},"ComprehensiveScanResults":{"allOf":[{"$ref":"#/components/schemas/ScanResults"},{"type":"object","properties":{"playbook":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["generating","complete"]},"skillCount":{"type":"number"},"topPrioritySkills":{"type":"array","items":{"type":"string"}}}},"aeoBoost":{"type":"object","properties":{"aeoScore":{"type":"number"},"companyName":{"type":"string"},"industry":{"type":"string"}}},"directoryListing":{"type":"object","properties":{"businessName":{"type":"string"},"slug":{"type":"string"},"industry":{"type":"string"}}}}}]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type identifier (e.g. 'not_found', 'rate_limited')"},"code":{"type":"string","description":"Machine-readable error code (e.g. 'SCAN_NOT_FOUND')"},"message":{"type":"string","description":"Human-readable error description with resolution hint"},"details":{"type":"object","additionalProperties":true,"description":"Additional context about the error"}},"required":["error","message"]}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_url":{"summary":"Invalid URL provided","value":{"error":"bad_request","code":"INVALID_URL","message":"Please provide a valid website URL","details":{"field":"url","expected":"domain or full URL"}}}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_not_found":{"summary":"Scan ID not found","value":{"error":"not_found","code":"SCAN_NOT_FOUND","message":"Scan not found. Check the scan ID and try again.","details":{"field":"scanId"}}}}}}},"RateLimited":{"description":"Rate limit exceeded. Check Retry-After header.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until you can retry"},"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Max requests per window"},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in window"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"error":"rate_limited","code":"RATE_LIMIT","message":"Too many requests. Please wait 60 seconds and try again.","details":{"retry_after_seconds":60}}}}}}}}},"tags":[{"name":"Meta","description":"API health, discovery, and metadata"},{"name":"Scanning","description":"Website scanning, status tracking, and results retrieval"},{"name":"Analysis","description":"Detailed analysis, playbooks, and search"},{"name":"Directory","description":"AI Business Directory browsing and lookup"},{"name":"Analytics","description":"Aggregate analytics and trends"},{"name":"Webhooks","description":"Real-time event subscriptions"}],"externalDocs":{"description":"Flowtivity Developer Portal — quickstart guides, integration options, and full documentation","url":"https://flowtivity.ai/developers/"},"x-webhooks":{"scan.completed":{"post":{"summary":"Scan completed","description":"Sent when a scan finishes successfully","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","example":"scan.completed"},"timestamp":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"scan_id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"status":{"type":"string"},"scores":{"type":"object","properties":{"readiness":{"type":"number"},"aeo":{"type":"number"}}}}}}}}}}}}}}