{"openapi":"3.1.0","info":{"title":"StackOS AI Plugin, MCP & Subscription Decision Router API","version":"1.4.0","description":"Versioned (/api/v1/) public read-only API and OpenAI Action schema for evaluating B2B software stacks, calculating deterministic multi-seat 12 & 36-month SaaS TCO (/api/v1/tco), recommending $0 open-source MCP servers alongside Freemium/Paid SaaS APIs, querying live global search & developer community trends, and generating ready-to-paste .mcp.json configurations. Free tier requires zero authentication; optional self-serve OAuth2 sandbox tokens are issued instantaneously at POST /api/auth/token.","contact":{"name":"Vishal Singh — StackOS API Support","url":"https://stackos-ai.vercel.app/docs","email":"thevishalrajput@gmail.com"}},"x-deprecation-policy":{"strategy":"url-path-and-header","currentVersion":"v1","versionHeader":"X-API-Version","sunsetNoticeDays":90,"headers":["Deprecation","Sunset","Link"]},"security":[{},{"stackosReadOAuth":["catalog:read","router:read","benchmarks:read","trends:read"]}],"servers":[{"url":"https://stackos-ai.vercel.app","description":"StackOS Primary Clean B2B Production & Zero-Auth Sandbox Domain"},{"url":"https://stackos-ai.vercel.app","description":"StackOS Canonical Alias"}],"paths":{"/api/auth/token":{"post":{"operationId":"issueSelfServeSandboxToken","summary":"Issue instant self-serve OAuth2 read-only sandbox token (no signup required)","x-openai-isConsequential":false,"security":[{}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","description":"Space-separated least-privilege read scopes to request.","default":"catalog:read router:read benchmarks:read trends:read"}}}}}},"responses":{"200":{"description":"Issued OAuth 2.0 Bearer token with explicit least-privilege read scopes","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer","example":3600},"scope":{"type":"string","example":"catalog:read router:read benchmarks:read trends:read"}}}}}}}}},"/api/v1/router":{"get":{"operationId":"listOrRouteV1Plugins","summary":"List or filter v1 MCP servers, CLI extensions, and SaaS API connectors","x-openai-isConsequential":false,"security":[{},{"stackosReadOAuth":["catalog:read","router:read"]}],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Optional natural-language task query to score and route matching tools."},{"name":"tier","in":"query","schema":{"type":"string","enum":["all","free","premium"],"default":"all"},"description":"Filter by free open-source MCPs or premium/freemium connectors."}],"responses":{"200":{"description":"Versioned v1 catalog or routed stack recommendation","headers":{"X-API-Version":{"schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"apiVersion":{"type":"string","example":"v1"},"total":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PluginRecommendation"}}}}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"operationId":"decideV1PluginStack","summary":"Recommend Free open-source MCP servers and Paid SaaS APIs with .mcp.json bundle (v1)","x-openai-isConsequential":false,"security":[{},{"stackosReadOAuth":["router:read","benchmarks:read"]}],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideRequest"}}}},"responses":{"200":{"description":"Matched Free auto-connect tools, Premium connectors, and .mcp.json blueprint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideResponse"}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/tco":{"get":{"operationId":"calculateStackTcoGet","summary":"Calculate deterministic 12-month & 36-month multi-seat SaaS stack TCO and migration savings","x-openai-isConsequential":false,"security":[{},{"stackosReadOAuth":["benchmarks:read"]}],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}},{"name":"stack","in":"query","required":false,"schema":{"type":"string","default":"n8n+apollo+hubspot-crm"},"description":"Plus-separated software slugs to model (up to 6 tools)."},{"name":"seats","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":10},"description":"Team seat count for workspace vs per-seat TCO modeling."}],"responses":{"200":{"description":"Multi-seat 12-month & 36-month SaaS TCO breakdown, partner perks, and migration playbooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackTcoAuditResponse"}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"operationId":"calculateStackTcoPost","summary":"Calculate multi-seat SaaS stack TCO from a JSON array or slug expression","x-openai-isConsequential":false,"security":[{},{"stackosReadOAuth":["benchmarks:read"]}],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["stack"],"properties":{"stack":{"oneOf":[{"type":"string","example":"n8n+apollo+hubspot-crm"},{"type":"array","items":{"type":"string"},"example":["n8n","apollo","hubspot-crm"]}]},"seats":{"type":"integer","minimum":1,"maximum":500,"default":10}}}}}},"responses":{"200":{"description":"Multi-seat 12-month & 36-month SaaS TCO breakdown, partner perks, and migration playbooks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StackTcoAuditResponse"}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/keyword-intel":{"get":{"operationId":"getLiveGlobalKeywordTrends","summary":"Fetch live Google & YouTube global search autocomplete buyer-intent trends across 24 markets","x-openai-isConsequential":false,"security":[{},{"stackosReadOAuth":["trends:read"]}],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Optional seed topic to mine live Google & YouTube autocomplete suggestions."},{"name":"market","in":"query","schema":{"type":"string","enum":["us","in","de","es","fr","br","jp","gb"],"default":"us"},"description":"Target country market code."}],"responses":{"200":{"description":"Live mined search trends and synthesized /trends/[slug] URLs","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"apiVersion":{"type":"string","example":"v1"},"totalAutoDiscovered":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"keyword":{"type":"string"},"marketLabel":{"type":"string"},"intent":{"type":"string"},"matchedToolName":{"type":"string"},"blufAnswer":{"type":"string"},"claudeCmd":{"type":"string"}}}}}}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/v1/community-radar":{"get":{"operationId":"getLiveCommunityBuyerRadar","summary":"Fetch live Hacker News, Dev.to, and GitHub MCP developer/buyer demand signals","x-openai-isConsequential":false,"security":[{},{"stackosReadOAuth":["trends:read"]}],"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}},{"name":"platform","in":"query","schema":{"type":"string","enum":["hacker-news","dev-to","github-mcp"]},"description":"Optional community source filter."}],"responses":{"200":{"description":"Live community threads, trending MCP repos, and matched StackOS benchmarks","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"apiVersion":{"type":"string","example":"v1"},"totalSignals":{"type":"integer"},"signals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"platform":{"type":"string"},"title":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"trendLandingUrl":{"type":"string","format":"uri"},"matchedToolName":{"type":"string"},"claudeInstallCmd":{"type":"string"}}}}}}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/plugins/decide":{"post":{"operationId":"decidePluginStack","summary":"Recommend Free and Premium plugins, MCP servers, skills, and subscription tiers for a task","x-openai-isConsequential":false,"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideRequest"}}}},"responses":{"200":{"description":"Matched Free auto-connect tools, Premium connectors, and .mcp.json blueprint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideResponse"}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/api/plugins/catalog":{"get":{"operationId":"getPluginCatalog","summary":"List Free open-source and Premium API-backed plugins, MCP servers, and skills","x-openai-isConsequential":false,"parameters":[{"name":"X-API-Version","in":"header","required":false,"description":"Optional date-pinned API version header (default: 2026-11-19). Breaking changes use new /api/v2/ paths with 90-day RFC 8594 Deprecation and Sunset headers.","schema":{"type":"string","default":"2026-11-19"}},{"name":"tier","in":"query","schema":{"type":"string","enum":["all","free","premium"]},"description":"Filter by free open-source or premium/freemium connectors."},{"name":"domain","in":"query","schema":{"type":"string"},"description":"Optional domain filter such as voice-video, browser-scraping, coding-review, database-backend, automation-agents, seo-growth, crm-commerce, or design-docs."}],"responses":{"200":{"description":"Catalog of available plugins and connectors","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PluginRecommendation"}}}}}}},"400":{"description":"Bad Request — invalid parameter or malformed JSON payload (RFC 9457 Problem Details)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found — requested resource or endpoint does not exist","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"429":{"description":"Too Many Requests — rate limit exceeded (120 requests per 60 seconds; honor Retry-After)","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","example":60}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal Server Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"securitySchemes":{"stackosReadOAuth":{"type":"oauth2","description":"Optional least-privilege OAuth 2.0 scopes issued via POST /api/auth/token; baseline read endpoints also allow zero-auth public access.","flows":{"clientCredentials":{"tokenUrl":"https://stackos-ai.vercel.app/api/auth/token","scopes":{"catalog:read":"Read B2B SaaS & MCP connector catalog entries","router:read":"Evaluate task prompts and generate .mcp.json configurations","benchmarks:read":"Read 108-point pricing and TCO comparison benchmarks","trends:read":"Read live Google, YouTube, Hacker News, Dev.to, and GitHub MCP trends"}}}}},"schemas":{"DecideRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"The user workflow, coding, automation, voice, scraping, SEO, or CRM requirement."},"platform":{"type":"string","enum":["chatgpt","claude-code","claude-web","cursor","gemini-cli","windsurf","plugin-hub"],"default":"chatgpt"},"includePaid":{"type":"boolean","default":true,"description":"Include Freemium and Paid API-backed connectors with subscription rules and partner links."},"maxBudgetUsd":{"type":"number","description":"Optional monthly budget cap per connector in USD."}}},"DecideResponse":{"type":"object","properties":{"apiVersion":{"type":"string"},"summaryEn":{"type":"string"},"summaryHi":{"type":"string"},"freeAutoConnect":{"type":"array","items":{"$ref":"#/components/schemas/PluginRecommendation"}},"premiumPowerUps":{"type":"array","items":{"$ref":"#/components/schemas/PluginRecommendation"}},"connectionBlueprint":{"type":"object","properties":{"steps":{"type":"array","items":{"type":"string"}},"freeOnlyMcpJson":{"type":"string"},"fullStackMcpJson":{"type":"string"},"claudeCodeCommands":{"type":"array","items":{"type":"string"}},"oneLineAutoInstallCmd":{"type":"string"},"estimatedMonthlyStarterUsd":{"type":"number"}}}}},"PluginRecommendation":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string"},"kind":{"type":"string"},"pricingModel":{"type":"string"},"priceBadge":{"type":"string"},"freeTierSummary":{"type":"string"},"paidSubscriptionRule":{"type":"string"},"claudeCodeCmd":{"type":"string"},"setupUrl":{"type":"string"},"affiliateTrackingShortlink":{"type":["string","null"]},"partnerPerk":{"type":"string"}}},"StackTcoAuditResponse":{"type":"object","properties":{"apiVersion":{"type":"string","example":"v1"},"stackSlug":{"type":"string","example":"n8n+apollo+hubspot-crm"},"seats":{"type":"integer","example":10},"shareableAuditUrl":{"type":"string","format":"uri"},"totalMonthlyUsd":{"type":"number"},"total12MonthMonthlyBilledUsd":{"type":"number"},"total12MonthAnnualDiscountUsd":{"type":"number"},"annualBillingSavingsUsd":{"type":"number"},"total36MonthDiscountedUsd":{"type":"number"},"tools":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"billingModel":{"type":"string","enum":["workspace-flat","per-seat"]},"freePlanAvailable":{"type":"boolean"},"monthlyUsdAtSeats":{"type":"number"},"annualMonthlyBilledUsd":{"type":"number"},"annualDiscountedUsd":{"type":"number"},"threeYearDiscountedUsd":{"type":"number"},"partnerPerk":{"type":["string","null"]},"mcpCommand":{"type":["string","null"]},"setupShortlink":{"type":"string","format":"uri"}}}},"seatMatrix":{"type":"array","items":{"type":"object","properties":{"seats":{"type":"integer"},"monthlyUsd":{"type":"number"},"annualDiscountedUsd":{"type":"number"},"threeYearUsd":{"type":"number"}}}},"matchedMigrations":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"string"},"savingsPercent":{"type":"number"},"playbookUrl":{"type":"string","format":"uri"}}}}}},"ProblemDetails":{"type":"object","description":"RFC 9457 Problem Details structured JSON error response","required":["type","title","status","code","detail","resolution"],"properties":{"type":{"type":"string","format":"uri","example":"https://stackos-ai.vercel.app/docs#error-missing_query_field"},"title":{"type":"string","example":"Missing required query field"},"status":{"type":"integer","example":400},"code":{"type":"string","example":"missing_query_field"},"detail":{"type":"string","example":"POST /api/v1/router requires a non-empty query string."},"resolution":{"type":"string","example":"Include {\"query\":\"<task>\"} in the JSON request body."}}}}}}