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

Sign up at Brave Search API
Subscribe to a plan (Free tier available, credit card required for anti-fraud)
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

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
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

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

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

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

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

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

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

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

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

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

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

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

brave-search

NPX Install

Tags

SKILL.md Content

Brave Search API

When to Use

Prerequisites

Pricing

How to Use

1. Basic Web Search

2. Web Search with Parameters

3. Safe Search Filter

4. Freshness Filter

5. Image Search

6. Video Search

7. News Search

8. Pagination

9. Get Raw JSON Response

Response Structure

Web Search Response

Image Search Response

Guidelines