brave-api-search

Files (6)

• origin.json · .clawhub/
• SKILL.md
• _meta.json
• brave_answers.js
• brave_search.js
• skill.json

SKILL.md (first lines)

# Brave API Search

Real-time web search and AI-powered answers using the official Brave Search API. Two tools:
- `brave_search` — web results with titles, URLs, descriptions, optional AI summary
- `brave_answers` — AI-grounded answers with inline citations powered by live web search

## Setup

Set your Brave API keys in a local `.env` file (recommended):

```bash
# .env (do not commit)
BRAVE_SEARCH_API_KEY=your_key_here
BRAVE_ANSWERS_API_KEY=your_key_here
```

Or export them in your shell session if needed.

Get your keys at: https://api-dashboard.search.brave.com

Both keys can be the same if your plan supports both Search and AI Answers endpoints.

> Note: This skill explicitly requires `BRAVE_SEARCH_API_KEY` and `BRAVE_ANSWERS_API_KEY`. It does **not** use a generic `BRAVE_API_KEY` fallback.

## When to Use This Skill

**Use `brave_search` when:**
- Searching for current information, news, or recent events
- Looking up documentation or technical references
- Need ranked results with URLs to follow up on
- Want an AI summary of search results

**Use `brave_answers` when:**
- Need a synthesized answer with cited sources
- Researching topics that benefit from multiple sources
- Want AI-grounded responses with inline citations
- Deep research mode needed (multi-search)

**Don't use this skill for:**
- Questions already answered from context or memory
- Tasks that don't require external information

## Tools

### brave_search

Web search returning ranked results with titles, URLs, and descriptions.

```
brave_search(query="latest Node.js release", count=5)
brave_search(query="TypeScript generics", extra_snippets=true)
brave_search(query="current weather Copenhagen", freshness="pd")
brave_search(query="React Server Components", summary=true)
```

**Parameters:**
- `query` (required) — Search query, supports operators: `site:`, `"exact phrase"`, `-exclude`
- `count` — Results to return (1-20, default: 10)
- `country` — 2-letter country code (default: `us`)
- `freshness` — Date filter: `pd` (24h), `pw` (7 days), `pm` (31 days), `py` (1 year)
- `extra_snippets` — Include up to 5 extra text excerpts per result (default: false)
- `summary` — Fetch Brave AI summarizer result (default: false)

**Returns:** Formatted list of results with title, URL, description, and optional AI summary.

### brave_answers

AI-powered answers grounded in live web search with inline citations.

```
brave_answers(query="How does React Server Components work?")
brave_answers(query="Compare Postgres vs MySQL for OLAP", enable_research=true)
brave_answers(query="Latest Python release notes", enable_citations=true)
```

**Parameters:**
- `query` (required) — Question or topic to research
- `enable_citations` — Include inline source citations (default: true)
- `enable_research` — Multi-search deep research mode (default: false)
- `country` — Target country for search context (default: `us`)

**Returns:** AI answer with cited sources extracted from the response, plus token usage.

## Pricing & Limits

Brave pricing is credit-based and can change. Do **not** assume a fixed free request count.

Current public guidance (verify in Brave dashboard/docs before production use):
- Monthly trial credits may be offered (e.g. `$5 in monthly credits`)
- Search and Answers consume credits differently
- Answers may also include token-based costs
- QPS limits depend on your plan tier

Always check your live limits and usage in:
- https://api-dashboard.search.brave.com
- https://brave.com/search/api/

## Security & Packaging Notes

- This skill only calls Brave official endpoints under `https://api.search.brave.com/res/v1`.
- It requires exactly two env vars: `BRAVE_SEARCH_API_KEY` and `BRAVE_ANSWERS_API_KEY` (keep them in `.env`, not inline in commands/chats).
- It does not request persistent/system privileges and does not modify system config.
- It is source-file based (two local Node scripts), with no external install/download step.

## API vs Web Scraping

This skill uses the **official Brave Search API** — not web scraping. Benefits:
- Reliable, structured JSON responses
- Rate limit headers and proper error messages
- Access to AI summarizer and AI answers endpoints
- Terms of service compliant

From fangxueming/openclaw-workspace, MIT.

More from fangxueming/openclaw-workspace