Brave Search

Brave Search API

Use the Brave Search API via direct curl calls to perform privacy-focused web searches with no user tracking.

Official docs: https://api.search.brave.com/app/documentation

When to Use

Use this skill when you need to:

• Web search with privacy-focused results
• Image search for finding images
• Video search for video content
• News search for current events
• AI-powered summaries of search results

Prerequisites

1. Sign up at Brave Search API
2. Subscribe to a plan (Free tier available, credit card required for anti-fraud)
3. Get your API key from the Dashboard

export BRAVE_API_KEY="your-api-key"

Pricing

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

How to Use

All examples below assume you have BRAVE_API_KEY set.

The base URL for the API is:

• https://api.search.brave.com/res/v1

Authentication uses the X-Subscription-Token header.

1. Basic Web Search

Search the web with a query:

bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search?q=artificial+intelligence" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}"' | jq '.web.results[:3] | .[] | {title, url, description}

2. Web Search with Parameters

Customize search with country, language, and result count:

Write to /tmp/brave_query.txt:

best restaurants

bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "country=us" -d "search_lang=en" -d "count=5"' | jq '.web.results[] | {title, url}'

Parameters:

• q: Search query (required, max 400 chars / 50 words)
• country: Two-letter country code (e.g., us, gb, jp)
• search_lang: Language code (e.g., en, zh, ja)
• count: Results per page (1-20, default: 10)
• offset: Pagination offset (0-9, default: 0)

3. Safe Search Filter

Control explicit content filtering:

Write to /tmp/brave_query.txt:

programming tutorials

bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "safesearch=strict"' | jq '.web.results[:3] | .[] | {title, url}

Options: off, strict (Note: Image/Video search only supports off and strict)

4. Freshness Filter

Filter results by time:

Write to /tmp/brave_query.txt:

tech news

bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "freshness=pd"' | jq '.web.results[:3] | .[] | {title, url, age}

Options:

• pd: Past day (24 hours)
• pw: Past week
• pm: Past month
• py: Past year
• YYYY-MM-DDtoYYYY-MM-DD: Custom date range

5. Image Search

Search for images:

Write to /tmp/brave_query.txt:

sunset beach

bash -c 'curl -s "https://api.search.brave.com/res/v1/images/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=5" -d "safesearch=strict"' | jq '.results[] | {title, url: .properties.url, thumbnail: .thumbnail.src}

Image search supports up to 200 results per request.

6. Video Search

Search for videos:

Write to /tmp/brave_query.txt:

learn python

bash -c 'curl -s "https://api.search.brave.com/res/v1/videos/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=5"' | jq '.results[] | {title, url, duration}

Video search supports up to 50 results per request.

7. News Search

Search for recent news articles:

Write to /tmp/brave_query.txt:

technology

bash -c 'curl -s "https://api.search.brave.com/res/v1/news/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=3"' | jq '.results[:3] | .[] | {title, url, age}

News search defaults to past day (pd) freshness.

8. Pagination

Get more results with offset:

Write to /tmp/brave_query.txt:

machine learning

bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=10" -d "offset=1"' | jq '.web.results[] | {title, url}

offset=1 skips the first page of results.

9. Get Raw JSON Response

View the full response structure:

bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search?q=test" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}"' | jq 'keys'

Response includes: query, mixed, type, web, videos, news, etc.

Response Structure

Web Search Response

{
  "query": { "original": "search term" },
  "web": {
  "results": [
  {
  "title": "Page Title",
  "url": "https://example.com",
  "description": "Page description...",
  "age": "2 days ago"
  }
  ]
  }
}

Image Search Response

{
  "results": [
  {
  "title": "Image Title",
  "properties": { "url": "https://..." },
  "thumbnail": { "src": "https://..." }
  }
  ]
}

Guidelines

1. URL encode queries: Use --data-urlencode for special characters
2. Respect rate limits: Free tier is 1 query/second
3. Use freshness for news: Time-sensitive searches benefit from pd or pw
4. Pagination limit: Maximum offset is 9 (100 results total with count=10)
5. Pro plan for local: Local business search requires Pro subscription
6. No tracking: Brave doesn't track users or store search history