{ "openapi": "3.1.0", "info": { "title": "FutureStack AI Tools Directory API", "version": "1.0.0", "description": "Public, agent-ready REST API for FutureStack (usefuturestack.com). Search, compare, and query 500+ community-vetted AI software tools, pricing plans, categories, and verified reviews. Ideal for LLM function calling and autonomous agent workflows.", "contact": { "name": "FutureStack Team", "email": "team.futurestack@gmail.com", "url": "https://www.usefuturestack.com/contact" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://www.usefuturestack.com", "description": "Production Server" } ], "tags": [ { "name": "Tools", "description": "AI tool discovery, search, details, and machine-readable data" }, { "name": "Categories", "description": "Taxonomy and role classifications" }, { "name": "Agent Protocols", "description": "MCP and LLM integration endpoints" } ], "paths": { "/api/tools": { "get": { "tags": [ "Tools" ], "summary": "List and search AI tools", "description": "Search and filter AI tools with pagination, role filtering, pricing models, and sorting.", "operationId": "listTools", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Search keyword matched against tool name, short description, and killer features.", "schema": { "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Category filter (e.g. 'Coding', 'Writing', 'Image Generation', 'Developer Tools', 'Marketing', 'Productivity', 'Design', 'Research', 'Chatbot', 'AI Agents', 'Audio', 'Video').", "schema": { "type": "string" } }, { "name": "role", "in": "query", "required": false, "description": "Target audience role filter (e.g. 'Developer', 'Student', 'Marketer', 'Founder', 'Designer', 'Content Creator', 'Freelancer').", "schema": { "type": "string" } }, { "name": "pricing", "in": "query", "required": false, "description": "Pricing model filter.", "schema": { "type": "string", "enum": [ "Free", "Freemium", "Paid", "Free Trial", "All Pricing" ] } }, { "name": "sort", "in": "query", "required": false, "description": "Sort order.", "schema": { "type": "string", "enum": [ "popular", "newest", "rising", "rating" ], "default": "popular" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "description": "Number of tools per page (max 50).", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 12 } } ], "responses": { "200": { "description": "List of AI tools matching query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolListResponse" } } } }, "400": { "description": "Invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/tools/{slug}": { "get": { "tags": [ "Tools" ], "summary": "Get tool details by slug", "description": "Retrieve comprehensive metadata for a specific AI tool including pricing plans, reviews, upvotes, and alternative tools.", "operationId": "getToolBySlug", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The unique URL slug of the tool (e.g. 'cursor', 'claude', 'chatgpt').", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detailed tool metadata and pricing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDetailResponse" } } } }, "404": { "description": "Tool not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/data/tools/{slug}": { "get": { "tags": [ "Tools" ], "summary": "Get machine-readable Markdown for tool", "description": "Returns an LLM-optimized Markdown representation of a tool's specifications, pricing matrix, and use cases.", "operationId": "getToolMarkdown", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The unique slug of the tool.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Structured Markdown document.", "content": { "text/markdown": { "schema": { "type": "string", "example": "# Cursor\n\n> The AI Code Editor..." } } } }, "404": { "description": "Tool not found.", "content": { "text/markdown": { "schema": { "type": "string", "example": "Tool not found. See sitemap at /llms.txt" } } } } } } }, "/api/tools/trending": { "get": { "tags": [ "Tools" ], "summary": "Get trending AI tools", "description": "Returns the top trending AI tools based on recent community engagement and upvotes.", "operationId": "getTrendingTools", "responses": { "200": { "description": "List of trending tools.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendingResponse" } } } } } } }, "/api/tools/stack-of-the-day": { "get": { "tags": [ "Tools" ], "summary": "Get Stack of the Day", "description": "Returns today's community-featured spotlight AI tool.", "operationId": "getStackOfTheDay", "responses": { "200": { "description": "Today's spotlight tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StackOfTheDayResponse" } } } } } } }, "/api/tools/categories": { "get": { "tags": [ "Categories" ], "summary": "List all categories and roles", "description": "Returns all 12+ tool categories and supported audience roles with their URL slugs.", "operationId": "listCategories", "responses": { "200": { "description": "Category and role taxonomy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryListResponse" } } } } } } }, "/api/mcp": { "post": { "tags": [ "Agent Protocols" ], "summary": "Model Context Protocol (MCP) endpoint", "description": "Standard JSON-RPC 2.0 Streamable HTTP transport for Model Context Protocol. Supports 'tools/list', 'tools/call', 'resources/list', 'resources/read', 'initialize', and 'ping'.", "operationId": "callMcpEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" } } } }, "responses": { "200": { "description": "MCP JSON-RPC response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcResponse" } } } } } } }, "/llms.txt": { "get": { "tags": [ "Agent Protocols" ], "summary": "LLM Sitemap & Instructions", "description": "Standard llms.txt roadmap containing tool directories, role categories, and when-to-use instructions for autonomous agents.", "operationId": "getLlmsTxt", "responses": { "200": { "description": "Plain text / Markdown LLM instructions.", "content": { "text/plain": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "ToolSummary": { "type": "object", "required": [ "id", "name", "slug", "category", "pricing_badge" ], "properties": { "id": { "type": "string", "description": "Unique tool identifier" }, "name": { "type": "string", "description": "Tool display name" }, "slug": { "type": "string", "description": "Unique URL slug" }, "category": { "type": "string", "description": "Primary category" }, "pricing_badge": { "type": "string", "enum": [ "Free", "Freemium", "Paid", "Free Trial" ], "description": "Pricing tier" }, "short_description": { "type": "string", "nullable": true, "description": "One-line summary" }, "website_url": { "type": "string", "format": "uri", "description": "Official website URL" }, "logo_url": { "type": "string", "format": "uri", "nullable": true, "description": "Tool logo image URL" }, "upvotes": { "type": "integer", "default": 0, "description": "Total verified community upvotes" }, "avg_rating": { "type": "number", "default": 0, "description": "Average user review rating (0.0 - 5.0)" }, "review_count": { "type": "integer", "default": 0, "description": "Total reviews" }, "primary_role": { "type": "string", "nullable": true, "description": "Best-fit role" } } }, "ToolDetailResponse": { "type": "object", "required": [ "tool" ], "properties": { "tool": { "allOf": [ { "$ref": "#/components/schemas/ToolSummary" } ], "properties": { "description": { "type": "string", "description": "Full markdown description" }, "best_for": { "type": "string", "nullable": true, "description": "Target user segment" }, "features": { "type": "array", "items": { "type": "string" }, "description": "Key features list" }, "pricing_plans": { "type": "array", "items": { "type": "object", "properties": { "plan_name": { "type": "string" }, "price_monthly": { "type": "number", "nullable": true }, "price_yearly": { "type": "number", "nullable": true }, "is_popular": { "type": "boolean" }, "features": { "type": "array", "items": { "type": "string" } } } } } } } } }, "ToolListResponse": { "type": "object", "required": [ "tools", "total", "page", "totalPages" ], "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolSummary" } }, "total": { "type": "integer", "description": "Total matching tools" }, "globalTotal": { "type": "integer", "description": "Total active tools in directory" }, "page": { "type": "integer", "description": "Current page" }, "totalPages": { "type": "integer", "description": "Total available pages" } } }, "TrendingResponse": { "type": "object", "required": [ "trending" ], "properties": { "trending": { "type": "array", "items": { "$ref": "#/components/schemas/ToolSummary" } } } }, "StackOfTheDayResponse": { "type": "object", "required": [ "success", "tool" ], "properties": { "success": { "type": "boolean" }, "tool": { "$ref": "#/components/schemas/ToolSummary" } } }, "CategoryListResponse": { "type": "object", "required": [ "categories", "roles" ], "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } }, "roles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "McpJsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "method": { "type": "string", "description": "MCP method e.g. tools/list, tools/call, initialize" }, "id": { "type": [ "string", "integer" ] }, "params": { "type": "object", "description": "Method arguments" } } }, "McpJsonRpcResponse": { "type": "object", "required": [ "jsonrpc", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer" ] }, "result": { "type": "object", "description": "MCP result object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object" } } } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "hint" ], "properties": { "code": { "type": "string", "example": "NOT_FOUND" }, "message": { "type": "string", "example": "The requested tool was not found." }, "hint": { "type": "string", "example": "Search for available tools using GET /api/tools?search=xyz or check /llms.txt" } } } } } } } }