{
  "openapi": "3.1.0",
  "info": {
    "agentName": "brave",
    "agentPath": "@microfox/brave",
    "title": "Brave Search",
    "version": "1.2.3",
    "mcpVersion": "1.0.2",
    "description": "An agent to search internet using brave search api with powerful tools for Web search, Image search, Video search and news search",
    "iconUrl": "https://raw.githubusercontent.com/microfox-ai/microfox/refs/heads/main/logos/brave.svg",
    "status": "stable",
    "contact": {
      "name": "Microfox Dev Support",
      "email": "support@microfox.com"
    }
  },
  "servers": [
    {
      "url": "https://api.microfox.com/c/brave",
      "description": "Unified wrapper endpoint"
    }
  ],
  "ai": {
    "systemPrompt": "This Agent can search the internet using the Brave Search API. It can search for web pages, images, videos, and news articles. When a user asks to perform an action, first find the necessary IDs (like channel or user IDs) using list or search functions before executing the action."
  },
  "security": [
    {
      "x-microfox-packages": ["@microfox/brave"]
    }
  ],
  "components": {
    "securitySchemes": {}
  },
  "paths": {
    "/imageSearch": {
      "post": {
        "operationId": "imageSearch",
        "summary": "Search for images using the Brave Search",
        "description": "Search for images using the Brave Search (with a query upto 20 images per toolcall)",
        "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": "Parameters for the image search function",
                        "properties": {
                          "q": {
                            "type": "string",
                            "description": "The search query",
                            "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",
                            "minimum": 1,
                            "maximum": 20
                          },
                          "offset": {
                            "type": "integer",
                            "description": "Pagination offset",
                            "minimum": 0,
                            "maximum": 9
                          },
                          "safesearch": {
                            "type": "string",
                            "description": "Content filtering level",
                            "enum": ["off", "moderate", "strict"]
                          },
                          "freshness": {
                            "type": "string",
                            "description": "Result freshness filter",
                            "oneOf": [
                              {
                                "enum": ["pd", "pw", "pm", "py"]
                              },
                              {
                                "type": "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",
                            "description": "Measurement units",
                            "enum": ["metric", "imperial"]
                          }
                        },
                        "required": ["q"]
                      }
                    },
                    "required": ["arguments"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful image search 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 - invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests - rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/newsSearch": {
      "post": {
        "operationId": "newsSearch",
        "summary": "Perform a news search using the Brave Search API.",
        "description": "This function allows users to search for news articles using the Brave Search API. It provides a wide range of parameters to customize the search, including query, country, language, and result filtering options. The function returns a promise that resolves to a detailed news search response containing article information and metadata.",
        "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": "Parameters for the news search function",
                        "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"]
                      },
                      "constructor": {
                        "type": "string",
                        "description": "Name of the constructor to use.",
                        "enum": ["createBraveSDK"]
                      }
                    },
                    "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 - invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/videoSearch": {
      "post": {
        "operationId": "videoSearch",
        "summary": "Performs a video search using the Brave Search API, retrieving video results with detailed metadata and thumbnails.",
        "description": "The videoSearch function allows users to search for videos using the Brave Search API. It provides a wide range of customizable search parameters, including query, country, language, result count, and various filters. The function returns detailed video results including metadata, thumbnails, and related information.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "object",
                    "description": "Body of the videoSearch sls call",
                    "properties": {
                      "arguments": {
                        "type": "object",
                        "description": "An object containing all the search parameters for the video search.",
                        "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"]
                      },
                      "constructor": {
                        "type": "string",
                        "description": "Name of the constructor to use.",
                        "enum": ["createBraveSDK"]
                      }
                    },
                    "required": ["arguments"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful video search response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "videos"
                    },
                    "query": {
                      "type": "object",
                      "properties": {
                        "original": {
                          "type": "string"
                        },
                        "altered": {
                          "type": "string"
                        },
                        "cleaned": {
                          "type": "string"
                        },
                        "spellcheck_off": {
                          "type": "boolean"
                        },
                        "show_strict_warning": {
                          "type": "boolean"
                        }
                      }
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "const": "video_result"
                          },
                          "url": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "age": {
                            "type": "string"
                          },
                          "page_age": {
                            "type": "string"
                          },
                          "page_fetched": {
                            "type": "string"
                          },
                          "thumbnail": {
                            "type": "object",
                            "properties": {
                              "src": {
                                "type": "string"
                              },
                              "width": {
                                "type": "integer"
                              },
                              "height": {
                                "type": "integer"
                              }
                            }
                          },
                          "video": {
                            "type": "object",
                            "properties": {
                              "duration": {
                                "type": "string"
                              },
                              "views": {
                                "type": "string"
                              },
                              "creator": {
                                "type": "string"
                              },
                              "publisher": {
                                "type": "string"
                              },
                              "tags": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              "author": {
                                "type": "object"
                              },
                              "requires_subscription": {
                                "type": "boolean"
                              }
                            }
                          },
                          "meta_url": {
                            "type": "object",
                            "properties": {
                              "source": {
                                "type": "string"
                              },
                              "domain": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/webSearch": {
      "post": {
        "operationId": "webSearch",
        "summary": "Search the web using the Brave Search",
        "description": "Search the web using the Brave Search (with a query upto 20 results per toolcall)",
        "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": "Configuration object containing all web 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. ( useful for news or local searches)",
                            "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 periods"
                              },
                              {
                                "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 has been 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-side issue"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          }
        }
      }
    }
  }
}