{"openapi":"3.1.0","info":{"title":"BotFriendly API","description":"A curated directory of services AI agents can actually use. Query, filter, and discover bot-friendly APIs, tools, and merchants.","version":"1.0.0","contact":{"url":"https://www.botfriendly.xyz"}},"servers":[{"url":"https://www.botfriendly.xyz/api/v1"}],"paths":{"/services":{"get":{"operationId":"listServices","summary":"List and filter services","description":"Returns a paginated list of bot-friendly services. Supports filtering by category, protocol support, auth method, and search.","parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug (e.g., think, browse, pay)"},{"name":"has_mcp","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to services with MCP servers"},{"name":"accepts_mpp","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to services accepting MPP payments"},{"name":"accepts_x402","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to services accepting x402 payments"},{"name":"has_skill_file","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to services with skill files"},{"name":"has_plugin_manifest","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to services with plugin manifests"},{"name":"has_llms_txt","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to services with llms.txt"},{"name":"has_agent_protocol","in":"query","schema":{"type":"string","enum":["true"]},"description":"Filter to services with agent protocol endpoints"},{"name":"auth_method","in":"query","schema":{"type":"string","enum":["api-key","m2m-oauth","bot-token","wallet","x402-none","none"]}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Full-text search across name, description, and tags"},{"name":"min_score","in":"query","schema":{"type":"integer","minimum":1,"maximum":5},"description":"Minimum bot-friendly score"},{"name":"promoted","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Filter by promoted status: true for promoted only, false for organic only"},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","votes","name","newest"],"default":"score"},"description":"Sort order: score (default), votes, name, newest"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"List of services","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total_pages":{"type":"integer"},"organic_count":{"type":"integer","description":"Number of organic (non-ad) results"},"ad_count":{"type":"integer","description":"Number of ad/promoted results"},"ad_positions":{"type":"array","items":{"type":"integer"},"description":"1-indexed positions of ads in the results array"}}}}}}}}}}},"/services/{slug}":{"get":{"operationId":"getService","summary":"Get a single service by slug","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service detail","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Service"}}}}}},"404":{"description":"Service not found"}}}},"/categories":{"get":{"operationId":"listCategories","summary":"List all 15 categories with service counts","responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"icon":{"type":"string"},"description":{"type":"string"},"service_count":{"type":"integer"}}}}}}}}}}}},"/featured":{"get":{"operationId":"getFeatured","summary":"Get site-wide promoted/featured services (max 3)","description":"Returns site-wide promoted services. These are paid placements clearly marked as promoted.","responses":{"200":{"description":"Featured services","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"meta":{"type":"object","properties":{"slots_total":{"type":"integer"},"slots_filled":{"type":"integer"}}}}}}}}}}},"/protocols":{"get":{"operationId":"listProtocols","summary":"List trackable protocols with adoption counts","responses":{"200":{"description":"Protocol stats"}}}},"/stats":{"get":{"operationId":"getStats","summary":"Directory statistics","responses":{"200":{"description":"Directory stats including total services and protocol coverage"}}}},"/submissions":{"post":{"operationId":"submitService","summary":"Submit a new service for review","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","url","category","description"],"properties":{"name":{"type":"string"},"url":{"type":"string","format":"uri"},"category":{"type":"string"},"description":{"type":"string","maxLength":120},"auth_method":{"type":"string"},"has_mcp_server":{"type":"boolean"},"mcp_server_url":{"type":"string"},"has_openapi_spec":{"type":"boolean"},"accepts_mpp":{"type":"boolean"},"accepts_x402":{"type":"boolean"},"has_skill_file":{"type":"boolean"},"skill_file_url":{"type":"string"},"has_plugin_manifest":{"type":"boolean"},"plugin_manifest_url":{"type":"string"},"has_llms_txt":{"type":"boolean"},"llms_txt_url":{"type":"string"},"has_structured_feed":{"type":"boolean"},"structured_feed_url":{"type":"string"},"has_agent_protocol":{"type":"boolean"},"agent_protocol_type":{"type":"string"},"billing_model":{"type":"string"},"has_free_tier":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"contact_email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Submission created"},"400":{"description":"Validation error"}}}},"/search":{"get":{"operationId":"searchServices","summary":"Full-text search across services","description":"Search services by keyword. Returns results ranked by bot_score.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query (full-text, websearch syntax)"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by category slug"},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"meta":{"type":"object","properties":{"query":{"type":"string"},"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}},"400":{"description":"Missing required query parameter 'q'"}}}},"/health":{"get":{"operationId":"healthCheck","summary":"Health check and endpoint discovery","responses":{"200":{"description":"Service health and available endpoints"}}}}},"components":{"schemas":{"Service":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"category":{"type":"string"},"url":{"type":"string","format":"uri"},"docs_url":{"type":"string","format":"uri","nullable":true},"icon_url":{"type":"string","format":"uri","nullable":true,"description":"Service icon URL"},"auth_method":{"type":"string","enum":["api-key","m2m-oauth","bot-token","wallet","x402-none","none"],"nullable":true},"has_mcp_server":{"type":"boolean"},"mcp_server_url":{"type":"string","nullable":true},"has_openapi_spec":{"type":"boolean"},"openapi_spec_url":{"type":"string","nullable":true},"accepts_mpp":{"type":"boolean"},"accepts_x402":{"type":"boolean"},"supports_acp":{"type":"boolean"},"supports_ucp":{"type":"boolean"},"has_skill_file":{"type":"boolean"},"skill_file_url":{"type":"string","nullable":true},"has_plugin_manifest":{"type":"boolean"},"plugin_manifest_url":{"type":"string","nullable":true},"has_llms_txt":{"type":"boolean"},"llms_txt_url":{"type":"string","nullable":true},"has_structured_feed":{"type":"boolean"},"structured_feed_url":{"type":"string","nullable":true},"has_agent_protocol":{"type":"boolean"},"agent_protocol_type":{"type":"string","nullable":true},"billing_model":{"type":"string","nullable":true},"has_free_tier":{"type":"boolean"},"has_webhooks":{"type":"boolean"},"programmatic_onboarding":{"type":"string","enum":["full","partial","none"],"nullable":true},"bot_friendly_tos":{"type":"string","enum":["explicit-welcome","neutral","restricts-bots","unknown"],"nullable":true},"bot_score":{"type":"integer","minimum":1,"maximum":5},"vote_count":{"type":"integer","description":"Community upvote count"},"tags":{"type":"array","items":{"type":"string"}},"is_verified":{"type":"boolean"},"promoted":{"type":"boolean","description":"Whether this is a paid promoted placement (ad)"},"ad":{"type":"boolean","description":"Whether this is an ad (redundant with promoted for compatibility)"},"promotion_type":{"type":"string","enum":["site","category"],"nullable":true,"description":"Type of promotion if promoted"},"created_at":{"type":"string","format":"date-time"},"last_verified_at":{"type":"string","format":"date-time","nullable":true}}}}}}