Brave Search API

Brave Search API provides fast, privacy-focused web search with region-specific and localized results.

Configuration

API credentials are stored in ~/.clawdbot/brave-search-config.json:

{
  "apiKey": "your_brave_search_api_key_here"
}

API Endpoint

Base URL: https://api.search.brave.com/res/v1/web/search

Search Query

curl -X GET 'https://api.search.brave.com/res/v1/web/search?q={query}' \
  -H 'Accept: application/json' \
  -H 'Accept-Encoding: gzip' \
  -H 'X-Subscription-Token: {apiKey}'

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query string
count	integer	No	Number of results (1-20, default: 20)
offset	integer	No	Pagination offset (default: 0)
country	string	No	2-letter country code (e.g., JP, US, GB, DE)
search_lang	string	No	ISO language code for search results (e.g., ja, en, de)
ui_lang	string	No	ISO language code for UI elements
safesearch	string	No	strict, moderate, or off (default: moderate)
freshness	string	No	pd, pw, pm, py (past day/week/month/year) or date range
text_decorations	boolean	No	Enable bolding of query terms (default: true)
spellcheck	boolean	No	Enable spellcheck (default: true)
result_filter	string	No	Filter results (web, news, images, videos)
units	string	No	Distance units (km, mi)

Response Format

{
  "web": {
    "results": [
      {
        "title": "Page Title",
        "url": "https://example.com",
        "description": "Page description...",
        "published": "2025-12-30T00:00:00+00:00",
        "author": ["Author Name"],
        "type": "web"
      }
    ]
  },
  "query": {
    "original": "search query",
    "cleaned": "search query"
  },
  "results_count": 1000000
}

Usage Examples

Basic Search

curl -X GET 'https://api.search.brave.com/res/v1/search?q=AI%20agents' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[] | {title, url}'

Japanese Results with Country Filter

curl -X GET 'https://api.search.brave.com/res/v1/search?q=AIエージェント&country=JP&search_lang=ja&ui_lang=ja' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[]'

Recent News (Past Week)

curl -X GET 'https://api.search.brave.com/res/v1/search?q=OpenAI&freshness=pw&result_filter=news' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[]'

Limited Results

curl -X GET 'https://api.search.brave.com/res/v1/search?q=Python%20programming&count=5' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[:3]'

Date Range Filter

curl -X GET 'https://api.search.brave.com/res/v1/search?q=AI%20research&freshness=2025-01-01to2025-12-31' \
  -H 'X-Subscription-Token: {apiKey}' \
  | jq '.web.results[]'

Helper Scripts

Quick Search

#!/bin/bash
# ~/.openclaw/workspace/skills/brave-search/scripts/search.sh

API_KEY=$(cat ~/.clawdbot/brave-search-config.json | jq -r '.apiKey')
QUERY="$1"

curl -s -X GET "https://api.search.brave.com/res/v1/search?q=$(printf '%s' "$QUERY" | jq -sRr @uri)" \
  -H "X-Subscription-Token: $API_KEY" \
  | jq '.web.results[] | {title, url}'

Japanese Search

#!/bin/bash
# ~/.openclaw/workspace/skills/brave-search/scripts/search_ja.sh

API_KEY=$(cat ~/.clawdbot/brave-search-config.json | jq -r '.apiKey')
QUERY="$1"

curl -s -X GET "https://api.search.brave.com/res/v1/search?q=$(printf '%s' "$QUERY" | jq -sRr @uri)&country=JP&search_lang=ja&ui_lang=ja" \
  -H "X-Subscription-Token: $API_KEY" \
  | jq '.web.results[]'

Country Codes

Common country codes:

• JP - Japan
• US - United States
• GB - United Kingdom
• DE - Germany
• FR - France
• ALL - All countries (default)

Language Codes

Common language codes:

• ja - Japanese
• en - English
• de - German
• fr - French
• es - Spanish

Freshness Values

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

Result Filters

• web - Web results (default)
• news - News articles
• images - Image search
• videos - Video search

Rate Limits

• Free tier: 2,000 requests per month
• Check subscription for current limits

Notes

• Always include X-Subscription-Token header with API key
• URL-encode query parameters
• Use jq for JSON parsing
• The API returns gzip-encoded responses by default
• Results include title, URL, description, and metadata