Brave Search API bindings: web search (https://api-dashboard.search.brave.com).

Setup: context variable brave.api.key (the subscription token), or a per-call api-key in the trailing opts Map of any API-calling function (see ::brave::search::api). Sent as X-Subscription-Token.

Quick start

out ::brave::search/search("rust jit compiler", {count: 5, freshness: "pm"})
map(out.web.results, (r) { `${r.title} - ${r.url}` })

Options use Brave's own names, and functions return Brave's own response. A failed call is an Err carrying ::brave::search::http/HttpError.

Context Vars

Optional
  • brave.api.key

Values

BASE_URL

BASE_URL: Str "https://api.search.brave.com/res/v1"

Functions

build-request

fn (path: Str, api-key: Str): ::hot::http/HttpRequest

The outgoing HttpRequest for a key. Pure; exposed for testing.

Example

req ::brave::search/build-request("/web/search?q=rust", "test-token")
req.url  // "https://api.search.brave.com/res/v1/web/search?q=rust"
req.headers  // {X-Subscription-Token: "test-token", Accept: "application/json"}

get-json

fn (path: Str): Any
fn (path: Str, api-key: Str?): Any
fn (path: Str, opts: Map): Any

GET a path under /res/v1 and return the decoded JSON, or an Err carrying ::brave::search::http/HttpError. search uses it. Call it directly for an endpoint this package has no function for. The optional second argument is an API key, or an opts Map (see ::brave::search::api).

Example

out ::brave::search/get-json("/web/search?q=rust&count=3")
map(out.web.results, (r) { r.url })

// With per-call credentials
::brave::search/get-json("/web/search?q=rust", {api-key: ::hot::ctx/get("tenant-b.brave.key")})
fn (query: Str): Map
fn (query: Str, options: Map): Map
fn (query: Str, options: Map, opts: Map): Map

GET /web/search - Brave web search. options: count (max 20), offset (page index, max 9), country, search_lang, safesearch ("off"/"moderate"/"strict"), freshness ("pd", "pw", "pm", "py", or a range like "2026-01-01to2026-06-30"), extra_snippets. Restrict sites with operators in the query (site:example.com, NOT site:example.com). Null options are dropped. Returns {web: {results: [{title, url, description}]}, ...}; titles and descriptions can contain <strong> markup and HTML entities.

Example

out ::brave::search/search("rust jit compiler", {count: 5, freshness: "pm"})
map(out.web.results, (r) { r.url })
Context Vars: brave.api.key