brave-search

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name BRAVE_API_KEY` or `zero doctor check-connector --url https://api.search.brave.com/res/v1/web/search --method GET`

## 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: $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: $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: $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: $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: $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: $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: $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: $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: $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