Agent skill

brave-search

Brave Search API for web search. Use when user says "search web", "Brave search", or asks to "find on web" without specifying Google.

View SKILL.md on GitHub Repository
Stars 50
Forks 8

Install this agent skill to your Project

npx add-skill https://github.com/vm0-ai/vm0-skills/tree/main/brave-search

SKILL.md

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
bash
export BRAVE_API_KEY="your-api-key"

Pricing

Plan Price Rate Limit Monthly Cap
Free $0 1 query/sec 2,000 queries
Base $5/1000 20 query/sec 20M queries
Pro $9/1000 50 query/sec Unlimited

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
curl -s "https://api.search.brave.com/res/v1/web/search?q=artificial+intelligence" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/images/search" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/videos/search" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/news/search" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv 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
curl -s "https://api.search.brave.com/res/v1/web/search?q=test" -H "Accept: application/json" -H "X-Subscription-Token: $(printenv BRAVE_API_KEY)" | jq 'keys'

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

Response Structure

Web Search Response

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

Image Search Response

json
{
  "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

Didn't find tool you were looking for?

Be as detailed as possible for better results