{ "openapi": "3.0.1", "info": { "title": "Brave SDK API", "version": "1.0.0", "mcp_version": "1.0.1", "description": "Single entry-point API for all Brave SDK functions via a wrapper Lambda", "contact": { "name": "Microfox Dev Support", "email": "support@microfox.com" } }, "servers": [ { "url": "https://api.microfox.com/c/brave", "description": "Unified wrapper endpoint" } ], "components": { "x-auth-packages": [ { "packageName": "@microfox/brave" } ] }, "paths": { "/imageSearch": { "post": { "operationId": "imageSearch", "summary": "The imageSearch function enables image search capabilities through the Brave Search API, allowing users to find and retrieve images based on search queries.", "description": "The imageSearch function provides a powerful interface to search for images using the Brave Search API. It accepts a wide range of parameters to customize the search, including query, language, country, content filtering, and result limits. The function returns a Promise that resolves to an object containing detailed image search results and metadata.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "object", "description": "Body of the imageSearch sls call", "properties": { "arguments": { "type": "object", "description": "Configuration object containing all function parameters", "properties": { "q": { "type": "string", "description": "The search query (max 400 characters, 50 words)", "maxLength": 400 }, "country": { "type": "string", "description": "Two-letter country code (e.g., 'US', 'GB')", "pattern": "^[A-Z]{2}$" }, "search_lang": { "type": "string", "description": "Language for search results" }, "ui_lang": { "type": "string", "description": "Language for user interface elements" }, "count": { "type": "integer", "description": "Number of results to return (maximum: 20)", "maximum": 20 }, "offset": { "type": "integer", "description": "Pagination offset (maximum: 9)", "maximum": 9 }, "safesearch": { "type": "string", "enum": ["off", "moderate", "strict"], "description": "Content filtering level" }, "freshness": { "type": "string", "description": "Result freshness filter (preset values: 'pd', 'pw', 'pm', 'py', or custom string)" }, "text_decorations": { "type": "boolean", "description": "Include text decoration markers in results" }, "spellcheck": { "type": "boolean", "description": "Enable automatic spell checking" }, "result_filter": { "type": "string", "description": "Comma-separated list of result types to include" }, "goggles": { "type": "array", "items": { "type": "string" }, "description": "Array of goggle definitions" }, "units": { "type": "string", "enum": ["metric", "imperial"], "description": "Measurement units" } }, "required": ["q"] } }, "required": ["arguments"] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "original": { "type": "string" }, "show_strict_warning": { "type": "boolean" }, "is_navigational": { "type": "boolean" }, "is_news_breaking": { "type": "boolean" }, "spellcheck_off": { "type": "boolean" }, "country": { "type": "string" }, "bad_results": { "type": "boolean" }, "should_fallback": { "type": "boolean" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "header_country": { "type": "string" }, "more_results_available": { "type": "boolean" }, "state": { "type": "string" } } }, "mixed": { "type": "object", "properties": { "type": { "type": "string" }, "main": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "source": { "type": "string" }, "source_favicon": { "type": "string" }, "source_domain": { "type": "string" }, "thumbnail": { "type": "object", "properties": { "src": { "type": "string" }, "original": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } } }, "size": { "type": "object", "properties": { "width": { "type": "number" }, "height": { "type": "number" } } }, "age": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "family_friendly": { "type": "boolean" } } } } } }, "type": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the bad request" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the server error" } } } } } } } } }, "/newsSearch": { "post": { "operationId": "newsSearch", "summary": "The newsSearch function performs a news search using the Brave Search API.", "description": "This function allows users to search for news articles using various parameters through the Brave Search API. It provides flexibility in specifying search criteria such as query, country, language, and result filtering. The function returns a promise that resolves to a comprehensive news search response containing detailed information about each article.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "object", "description": "Body of the newsSearch sls call", "properties": { "arguments": { "type": "object", "description": "NewsSearchParams object containing search parameters", "properties": { "q": { "type": "string", "description": "The search query (max 400 characters, 50 words)", "maxLength": 400 }, "country": { "type": "string", "description": "2-letter country code", "default": "US", "pattern": "^[A-Z]{2}$" }, "search_lang": { "type": "string", "description": "Search language", "default": "en" }, "ui_lang": { "type": "string", "description": "UI language", "default": "en-US" }, "count": { "type": "integer", "description": "Number of results (1-20)", "default": 20, "minimum": 1, "maximum": 20 }, "offset": { "type": "integer", "description": "Offset for pagination (0-9)", "default": 0, "minimum": 0, "maximum": 9 }, "safesearch": { "type": "string", "description": "Safe search level", "enum": ["off", "moderate", "strict"], "default": "moderate" }, "freshness": { "oneOf": [ { "type": "string", "enum": ["pd", "pw", "pm", "py"], "description": "Predefined freshness options" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}to\\d{4}-\\d{2}-\\d{2}$", "description": "Custom date range in format 'YYYY-MM-DDtoYYYY-MM-DD'" } ], "description": "Freshness of results" }, "text_decorations": { "type": "boolean", "description": "Include decoration markers", "default": true }, "spellcheck": { "type": "boolean", "description": "Enable spellchecking", "default": true }, "result_filter": { "type": "string", "description": "Comma-separated list of result types" }, "goggles": { "type": "array", "items": { "type": "string" }, "description": "Goggle definitions for custom re-ranking" }, "units": { "type": "string", "enum": ["metric", "imperial"], "description": "Units for measurements" } }, "required": ["q"] } }, "required": ["arguments"] } } } } } }, "responses": { "200": { "description": "Successful news search response", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "news" }, "query": { "type": "object", "properties": { "original": { "type": "string" }, "altered": { "type": "string" }, "cleaned": { "type": "string" } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "news_result" }, "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "age": { "type": "string" }, "page_age": { "type": "string" }, "page_fetched": { "type": "string" }, "breaking": { "type": "boolean" }, "thumbnail": { "type": "object", "properties": { "src": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } }, "meta_url": { "type": "object", "properties": { "source": { "type": "string" }, "domain": { "type": "string" } } }, "extra_snippets": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/webSearch": { "post": { "operationId": "webSearch", "summary": "Performs a web search using the Brave Search API.", "description": "This function allows users to perform web searches and retrieve results from the Brave Search API. It supports a wide range of search parameters including query, country, language, result count, and various filters. The function returns comprehensive search results including web pages, news, videos, discussions, FAQs, and more.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "object", "description": "Body of the webSearch sls call", "properties": { "arguments": { "type": "object", "description": "WebSearchParams object containing all search parameters", "properties": { "q": { "type": "string", "description": "The search query (max 400 characters, 50 words)", "maxLength": 400 }, "country": { "type": "string", "description": "2-letter country code", "default": "US", "minLength": 2, "maxLength": 2 }, "search_lang": { "type": "string", "description": "Search language", "default": "en" }, "ui_lang": { "type": "string", "description": "UI language", "default": "en-US" }, "count": { "type": "integer", "description": "Number of results (1-20)", "default": 20, "minimum": 1, "maximum": 20 }, "offset": { "type": "integer", "description": "Offset for pagination (0-9)", "default": 0, "minimum": 0, "maximum": 9 }, "safesearch": { "type": "string", "description": "Safe search level", "enum": ["off", "moderate", "strict"], "default": "moderate" }, "freshness": { "oneOf": [ { "type": "string", "enum": ["pd", "pw", "pm", "py"], "description": "Predefined freshness values" }, { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}to\\d{4}-\\d{2}-\\d{2}$", "description": "Custom date range in format 'YYYY-MM-DDtoYYYY-MM-DD'" } ], "description": "Freshness of results" }, "text_decorations": { "type": "boolean", "description": "Include decoration markers", "default": true }, "spellcheck": { "type": "boolean", "description": "Enable spellchecking", "default": true }, "result_filter": { "type": "string", "description": "Comma-separated list of result types", "pattern": "^(discussions|faq|infobox|news|query|summarizer|videos|web|locations)(,(discussions|faq|infobox|news|query|summarizer|videos|web|locations))*$" }, "goggles": { "type": "array", "items": { "type": "string" }, "description": "Goggle definitions for custom re-ranking" }, "units": { "type": "string", "enum": ["metric", "imperial"], "description": "Units for measurements" }, "extra_snippets": { "type": "boolean", "description": "Include up to 5 additional, alternative excerpts" }, "summary": { "type": "boolean", "description": "Enable summary key generation for use with summarizer" } }, "required": ["q"] } }, "required": ["arguments"] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "const": "search", "description": "Always 'search'" }, "discussions": { "type": "object", "description": "Optional discussions results" }, "faq": { "type": "object", "description": "Optional FAQ results" }, "infobox": { "type": "object", "description": "Optional infobox results" }, "locations": { "type": "object", "description": "Optional location results" }, "mixed": { "type": "object", "description": "Optional mixed results" }, "news": { "type": "object", "description": "Optional news results" }, "query": { "type": "object", "description": "Query information" }, "rich_data": { "type": "object", "description": "Optional rich data" }, "web": { "type": "object", "description": "Optional web search results" }, "videos": { "type": "object", "description": "Optional video results" } }, "required": ["type", "query"] } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the issue with the request" } }, "required": ["error"] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating authentication failure" } }, "required": ["error"] } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message indicating rate limit exceeded" }, "retry_after": { "type": "integer", "description": "Number of seconds to wait before retrying" } }, "required": ["error", "retry_after"] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing the server error" } }, "required": ["error"] } } } } } } } } }