{"openapi":"3.1.0","info":{"title":"Flaex AI Public API","version":"1.0.0","summary":"Programmatic access to the Flaex AI tools directory.","description":"The Flaex AI Public API lets agents and developers search the AI tools directory, discover tools by intent, fetch any page as clean markdown, subscribe emails to the newsletter, and interact with Flaex over the Model Context Protocol (MCP).","x-brand":"Flaex AI","contact":{"name":"Flaex AI","url":"https://www.flaex.ai/contact","email":"contact@flaex.ai"},"license":{"name":"Terms of Service","url":"https://www.flaex.ai/terms"}},"servers":[{"url":"https://www.flaex.ai","description":"Flaex AI production"}],"tags":[{"name":"search","description":"Discover AI tools by query or intent."},{"name":"content","description":"Fetch Flaex pages as agent-friendly content."},{"name":"newsletter","description":"Newsletter subscription management."},{"name":"mcp","description":"Model Context Protocol endpoint (Streamable HTTP)."}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authorization with scoped tokens. Discover metadata at /.well-known/oauth-authorization-server.","flows":{"authorizationCode":{"authorizationUrl":"https://www.flaex.ai/login","tokenUrl":"https://www.flaex.ai/api/auth/token","scopes":{"search:read":"Read access to tool search results.","directory:read":"Read access to directory listings and metadata.","newsletter:write":"Create newsletter subscriptions on behalf of a user.","mcp:invoke":"Call Flaex MCP tools over Streamable HTTP."}}}},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Optional API key. Keys can be issued with a subset of scopes (search:read, directory:read, newsletter:write, mcp:invoke) so callers only request the access they need."}},"schemas":{"Error":{"type":"object","description":"Structured error response returned by every API failure.","properties":{"error":{"type":"object","properties":{"code":{"type":"string","examples":["invalid_request"]},"message":{"type":"string"},"status":{"type":"integer"},"resolutionHints":{"type":"array","items":{"type":"string"},"description":"Actionable hints for recovering from this error."}},"required":["code","message"]}},"required":["error"]},"ToolResult":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"shortDescription":{"type":"string"},"pricing":{"type":"string"},"website":{"type":"string"}}},"SearchResponse":{"type":"array","items":{"$ref":"#/components/schemas/ToolResult"}}},"responses":{"BadRequest":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ServerError":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"security":[{"ApiKeyAuth":[]},{"OAuth2":["search:read"]}],"paths":{"/api/search":{"get":{"operationId":"searchTools","tags":["search"],"summary":"Semantic search across the AI tools directory.","description":"Searches the Flaex AI directory using semantic, hybrid, or intent-based discovery. Public; no authentication required. Rate limited to 60 requests/minute (10/min for mode=discover).","security":[{"ApiKeyAuth":["search:read"]}],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query, e.g. \"turn blog posts into videos\". In discover mode this is a problem description.","schema":{"type":"string","minLength":1}},{"name":"mode","in":"query","required":false,"description":"Search strategy.","schema":{"type":"string","enum":["semantic","hybrid","discover"],"default":"semantic"}},{"name":"pricing","in":"query","required":false,"description":"Filter by pricing model (e.g. Free, Freemium, Paid).","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Filter by category slug.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"A ranked list of matching tools.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"description":"Rate limited. Honor the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/markdown":{"get":{"operationId":"getPageMarkdown","tags":["content"],"summary":"Convert any Flaex page to clean markdown.","description":"Gateway used by Accept: text/markdown content negotiation. Requesting any flaex.ai page with Accept: text/markdown returns its markdown conversion directly; this endpoint is the explicit form.","security":[],"parameters":[{"name":"target","in":"query","required":true,"description":"Absolute URL of the page to convert.","schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Markdown rendering of the requested page.","content":{"text/markdown":{"schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Target page not found. Body is still markdown so agents can recover.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/api/newsletter/subscribe":{"post":{"operationId":"subscribeToNewsletter","tags":["newsletter"],"summary":"Subscribe an email address to the Flaex newsletter.","description":"Creates a newsletter subscription and sends a welcome email. Rate limited.","security":[{"ApiKeyAuth":["newsletter:write"]},{"OAuth2":["newsletter:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"Subscription result.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/api/mcp":{"post":{"operationId":"callMcpEndpoint","tags":["mcp"],"summary":"Flaex MCP server (Streamable HTTP transport).","description":"JSON-RPC 2.0 endpoint implementing the Model Context Protocol. Supports initialize, tools/list, and tools/call. Tools: flaex_search_tools, flaex_intent_discovery.","security":[{"ApiKeyAuth":["mcp:invoke"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":["string","integer","null"]},"method":{"type":"string","examples":["initialize","tools/list","tools/call"]},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"JSON-RPC response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/ServerError"}}},"get":{"operationId":"getMcpServerCard","tags":["mcp"],"summary":"MCP server capability document.","description":"Returns the MCP server card describing capabilities and transport.","security":[],"responses":{"200":{"description":"MCP server card.","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"x-mcp-server":{"transport":"streamable-http","endpoint":"https://www.flaex.ai/api/mcp","card":"https://www.flaex.ai/.well-known/mcp/server-card.json"},"externalDocs":{"description":"Flaex AI developer resources and agent guide","url":"https://www.flaex.ai/developers"}}