brave-search

Web search using the Brave Search API.

Prerequisites

• BRAVE_API_KEY environment variable with a valid Brave Search API key

Check before use:

[ -z "$BRAVE_API_KEY" ] && echo "Error: BRAVE_API_KEY not set" || echo "OK: BRAVE_API_KEY is set"

Note: Never hardcode BRAVE_API_KEY. Always use the environment variable.

API Endpoint

GET https://api.search.brave.com/res/v1/web/search

Web Search

Perform a web search query.

Request:

curl -s "https://api.search.brave.com/res/v1/web/search?q=your+query" \
  -H "X-Subscription-Token: $BRAVE_API_KEY" \
  -H "Accept: application/json"

Response:

{
  "query": {
    "original": "your query",
    "more_results_available": true
  },
  "web": {
    "results": [
      {
        "title": "Result Title",
        "url": "https://example.com/page",
        "description": "Snippet describing the page content...",
        "extra_snippets": ["Additional excerpt 1", "Additional excerpt 2"],
        "page_age": "2025-01-15",
        "profile": {
          "name": "Site Name",
          "img": "https://example.com/favicon.ico"
        }
      }
    ]
  }
}

Example Usage

# Basic search
curl -s "https://api.search.brave.com/res/v1/web/search?q=rust+web+frameworks" \
  -H "X-Subscription-Token: $BRAVE_API_KEY" | jq .

# Search with freshness filter (pd=day, pw=week, pm=month, py=year)
curl -s "https://api.search.brave.com/res/v1/web/search?q=ai+news&freshness=pw" \
  -H "X-Subscription-Token: $BRAVE_API_KEY" | jq .

# Search with country and language targeting
curl -s "https://api.search.brave.com/res/v1/web/search?q=nachhaltige+energie&country=DE&search_lang=de" \
  -H "X-Subscription-Token: $BRAVE_API_KEY" | jq .

# Extract just URLs and titles
curl -s "https://api.search.brave.com/res/v1/web/search?q=python+tutorials" \
  -H "X-Subscription-Token: $BRAVE_API_KEY" | \
  jq -r '.web.results[] | "\(.title): \(.url)"'

Query Parameters

Parameter	Type	Description
q	string	Required. Search query (URL-encoded).
count	integer	Results per page (max 20, default 20).
offset	integer	Pagination offset (0-9, default 0).
freshness	string	Time filter: pd (24h), pw (week), pm (month), py (year), or date range YYYY-MM-DDtoYYYY-MM-DD.
country	string	2-letter country code (e.g., US, DE, JP).
search_lang	string	Content language (ISO 639-1, e.g., en, de).
ui_lang	string	UI language (e.g., en-US).
safesearch	string	Filter level: off, moderate (default), strict.
extra_snippets	boolean	Include additional excerpts per result.
enable_rich_callback	integer	Set to 1 for rich results (weather, stocks, etc.).

Search Operators

Include operators directly in the q parameter:

Operator	Example	Description
""	"climate change"	Exact phrase match
-	javascript -jquery	Exclude term
site:	site:github.com rust	Search specific site
filetype:	filetype:pdf machine learning	Filter by file type

Response Fields

Field	Type	Description
query.original	string	The search query
query.more_results_available	boolean	Whether more results exist
web.results[]	array	Search results
web.results[].title	string	Page title
web.results[].url	string	Page URL
web.results[].description	string	Main snippet
web.results[].extra_snippets[]	array	Additional excerpts (if requested)
web.results[].page_age	string	Page publication date
web.results[].profile.name	string	Site name

Pagination

Check query.more_results_available before requesting the next page:

# Page 1 (offset=0, default)
curl -s "https://api.search.brave.com/res/v1/web/search?q=open+source&count=20" \
  -H "X-Subscription-Token: $BRAVE_API_KEY" | jq '.query.more_results_available'

# Page 2 (offset=1)
curl -s "https://api.search.brave.com/res/v1/web/search?q=open+source&count=20&offset=1" \
  -H "X-Subscription-Token: $BRAVE_API_KEY" | jq .

Error Handling

Status	Meaning
200	Success
401	Invalid or missing API key
429	Rate limit exceeded
500	Server error

Additional Search Endpoints

News Search

curl -s "https://api.search.brave.com/res/v1/news/search?q=breaking+news" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

Image Search

curl -s "https://api.search.brave.com/res/v1/images/search?q=nature+landscape" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

Video Search

curl -s "https://api.search.brave.com/res/v1/videos/search?q=tutorials" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"