{"openapi":"3.0.3","info":{"title":"FioTech Marketplace API","description":"Official RESTful OpenAPI 3.0 documentation for the FioTech ecosystem. Explore endpoints for querying decentralized applications, categories, admin metrics, and system health status.","version":"2.0.0","termsOfService":"https://fiotech.org/terms","contact":{"name":"FioTech Developer Support","email":"huan@fiotech.org","url":"https://fiotech.org"},"license":{"name":"MIT License","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"/","description":"Current Host / Deployment Environment"},{"url":"https://marketplace.fiotech.org","description":"Production Deployment"},{"url":"http://localhost:3000","description":"Local Development Server"}],"tags":[{"name":"Health","description":"System health check and database/cache connectivity status"},{"name":"Applications","description":"Discovery, query, filtering, and registration of ecosystem applications"},{"name":"Categories","description":"Application categories taxonomy and count metrics"},{"name":"Admin & Metrics","description":"Platform analytics, dashboard KPI cards, and time-series chart statistics"}],"paths":{"/api/health":{"get":{"tags":["Health"],"summary":"Check API & Service Health","description":"Returns the operational status of the FioTech Marketplace, including PostgreSQL connection and Upstash Redis cache status.","operationId":"getHealthStatus","responses":{"200":{"description":"System is healthy and operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"ok","app":"FioTech Marketplace","timestamp":"2026-09-02T09:45:00.000Z","services":{"database":"configured","upstashRedis":"configured"},"version":"2.0.0"}}}}}}},"/api/apps":{"get":{"tags":["Applications"],"summary":"List all applications","description":"Retrieve list of all ecosystem applications with optional category filtering and search query. Responses are cached with Upstash Redis for high speed.","operationId":"listApplications","parameters":[{"name":"category","in":"query","required":false,"description":"Filter by category slug (e.g., 'blockchain', 'defi', 'developer-tools', 'nft', 'analytics', 'governance', 'social', or 'all')","schema":{"type":"string","example":"defi"}},{"name":"search","in":"query","required":false,"description":"Search keyword matching application name, description, tags, or category","schema":{"type":"string","example":"wallet"}}],"responses":{"200":{"description":"Applications list successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationsListResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Applications"],"summary":"Submit a new application","description":"Register a new application in the FioTech Marketplace. Rate limited per IP address via Upstash Redis.","operationId":"createApplication","requestBody":{"required":true,"description":"Application payload to register","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApplicationRequest"},"example":{"name":"Fiotech Staking Portal","description":"Liquid staking portal for FioTech validators with auto-compounding rewards.","category":"defi","deploymentType":"Smart Contract / DApp","logoUrl":"/fiotech-logo.png","slug":"fiotech-staking-portal","appId":"APP-016","imageSlug":"staking","websiteUrl":"https://staking.fiotech.org","tags":["Staking","DeFi","Yield"],"stars":5,"usersCount":1500,"status":"active","isStaffPick":false,"isNewAndNoteworthy":true}}}},"responses":{"201":{"description":"Application successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleApplicationResponse"}}}},"400":{"description":"Validation Error (missing required fields)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded (Upstash Redis)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/apps/{slug}":{"get":{"tags":["Applications"],"summary":"Get application details by slug","description":"Retrieve complete metadata and details for a specific application by its unique slug identifier.","operationId":"getApplicationBySlug","parameters":[{"name":"slug","in":"path","required":true,"description":"Unique application slug (e.g. 'fiotech-wallet', 'fiotech-dex', 'fiotech-evm')","schema":{"type":"string","example":"fiotech-wallet"}}],"responses":{"200":{"description":"Application details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SingleApplicationResponse"}}}},"404":{"description":"Application not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/categories":{"get":{"tags":["Categories"],"summary":"List all categories","description":"Retrieve all marketplace categories with icons, descriptions, and active application counts.","operationId":"listCategories","responses":{"200":{"description":"Categories list retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesListResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/admin/metrics":{"get":{"tags":["Admin & Metrics"],"summary":"Get admin analytics & metrics","description":"Returns aggregated dashboard statistics, KPI cards, network node counts, time-series traffic points, and monthly revenue data for charts.","operationId":"getAdminMetrics","responses":{"200":{"description":"Admin metrics data retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminMetricsResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"Application":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"Fiotech Wallet"},"description":{"type":"string","example":"Next-generation multi-chain non-custodial Web3 wallet with biometric protection."},"category":{"type":"string","example":"blockchain"},"deploymentType":{"type":"string","example":"Web / Mobile"},"logoUrl":{"type":"string","example":"/fiotech-logo.png"},"slug":{"type":"string","example":"fiotech-wallet"},"longDescription":{"type":"string","example":"Fiotech Wallet is the official wallet of the FioTech ecosystem..."},"tags":{"type":"array","items":{"type":"string"},"example":["Wallet","Multi-Chain","Security","Web3"]},"appId":{"type":"string","example":"APP-001"},"imageSlug":{"type":"string","example":"wallet"},"websiteUrl":{"type":"string","example":"https://wallet.fiotech.org"},"stars":{"type":"integer","example":5},"usersCount":{"type":"integer","example":24500},"status":{"type":"string","enum":["active","beta","maintenance"],"example":"active"},"price":{"type":"string","example":"Free"},"isStaffPick":{"type":"boolean","example":true},"isNewAndNoteworthy":{"type":"boolean","example":true},"createdAt":{"type":"string","format":"date-time","example":"2024-01-15T00:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-01-15T00:00:00.000Z"}},"required":["name","description","category","slug","logoUrl","appId","imageSlug"]},"CreateApplicationRequest":{"type":"object","required":["name","description","category","slug","appId","imageSlug","logoUrl"],"properties":{"name":{"type":"string","example":"Fiotech Staking Portal"},"description":{"type":"string","example":"Liquid staking portal for FioTech validators."},"category":{"type":"string","example":"defi"},"deploymentType":{"type":"string","example":"Smart Contract / DApp"},"logoUrl":{"type":"string","example":"/fiotech-logo.png"},"slug":{"type":"string","example":"fiotech-staking-portal"},"longDescription":{"type":"string","example":"Detailed markdown description of the staking portal."},"tags":{"type":"array","items":{"type":"string"},"example":["Staking","DeFi"]},"appId":{"type":"string","example":"APP-016"},"imageSlug":{"type":"string","example":"staking"},"websiteUrl":{"type":"string","example":"https://staking.fiotech.org"},"stars":{"type":"integer","example":5},"usersCount":{"type":"integer","example":1000},"status":{"type":"string","example":"active"},"isStaffPick":{"type":"boolean","example":false},"isNewAndNoteworthy":{"type":"boolean","example":true}}},"Category":{"type":"object","properties":{"id":{"type":"integer","example":1},"name":{"type":"string","example":"DeFi"},"slug":{"type":"string","example":"defi"},"description":{"type":"string","example":"Decentralized finance protocols and trading"},"icon":{"type":"string","example":"TrendingUp"},"count":{"type":"integer","example":4}},"required":["name","slug"]},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"app":{"type":"string","example":"FioTech Marketplace"},"timestamp":{"type":"string","format":"date-time"},"services":{"type":"object","properties":{"database":{"type":"string","example":"configured"},"upstashRedis":{"type":"string","example":"configured"}}},"version":{"type":"string","example":"2.0.0"}}},"ApplicationsListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"source":{"type":"string","enum":["database","redis-cache"],"example":"redis-cache"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}}}},"SingleApplicationResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"source":{"type":"string","enum":["database","redis-cache"],"example":"database"},"data":{"$ref":"#/components/schemas/Application"}}},"CategoriesListResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"source":{"type":"string","enum":["database","redis-cache"],"example":"database"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}}},"AdminMetricsResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"cards":{"type":"object","properties":{"primary":{"type":"object","properties":{"title":{"type":"string","example":"Total Applications"},"value":{"type":"integer","example":15},"subtext":{"type":"string","example":"5 Staff Picks"}}},"warning":{"type":"object","properties":{"title":{"type":"string","example":"Pending Approvals"},"value":{"type":"integer","example":3},"subtext":{"type":"string","example":"Requires Action"}}},"success":{"type":"object","properties":{"title":{"type":"string","example":"Active Network Nodes"},"value":{"type":"integer","example":128},"subtext":{"type":"string","example":"99.98% Uptime"}}},"danger":{"type":"object","properties":{"title":{"type":"string","example":"System Alerts / Errors"},"value":{"type":"integer","example":0},"subtext":{"type":"string","example":"All Services Operational"}}}}},"stats":{"type":"object","properties":{"totalApps":{"type":"integer","example":15},"staffPicks":{"type":"integer","example":5},"newApps":{"type":"integer","example":6},"totalTransactions":{"type":"integer","example":1420950},"isUpstashConfigured":{"type":"boolean","example":true}}},"areaChartData":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"Mar 1"},"value":{"type":"integer","example":10000},"volume":{"type":"integer","example":15400}}}},"barChartData":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","example":"January"},"revenue":{"type":"integer","example":4215}}}}}}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string","example":"Application not found"}}}}}}