# Brave

Web results with descriptions and extra snippets; native LLM Context and answer APIs have separate contracts.

Canonical: https://searchsdk.dev/docs/providers/brave
Markdown: https://searchsdk.dev/docs/providers/brave.md

<a id="overview"></a>

## Normalized search

> **TypeScript reference**
> The API names, code and policy behavior in this article describe the TypeScript SDK. See [your language guide](https://searchsdk.dev/docs/sdks) for its supported surface and limits.

Normalized search reads `web.results`, maps descriptions to snippets, and retains extra snippets as highlights. A valid query echo without a web section is accepted as empty web results. Unreported usage is `null`.

**brave-search.ts · server**

```typescript
import { createSearch } from '@belweave/search-sdk';
import { brave } from '@belweave/search-sdk/brave';

const apiKey = process.env.BRAVE_API_KEY;
if (!apiKey) throw new Error('BRAVE_API_KEY is required');

const client = createSearch({ provider: brave({ apiKey }) });
const response = await client.web.search({
  query: 'SQLite write concurrency',
  limit: 5,
});
console.log(response.results, response.attempts);
```

The normalized adapter does not support domain-filter options. Adding it to a filtered fallback chain fails preflight. Native rich results, local information, images, news, and LLM Context must keep their original shapes.

Domain filters unavailable on the normalized adapter.

<a id="native-client"></a>

## Provider-native client

**brave-native.ts · server**

```typescript
import { createBraveClient } from '@belweave/search-sdk/native-brave';

const apiKey = process.env.BRAVE_API_KEY;
if (!apiKey) throw new Error('BRAVE_API_KEY is required');

const client = createBraveClient({ apiKey, timeoutMs: 10_000 });
const response = await client.search({ query: { q: 'SQLite write concurrency', count: 5 } });
console.log(response.data, response.metadata);
```

Read provider data from `response.data` and sanitized transport details from `response.metadata`. Native TypeScript response types are not runtime schema validation. Preserve the operation's native response and source identities.

<a id="operations"></a>

## Native operation inventory

Methods available on this native client. Paths are relative to each operation's fixed base; a provider may use more than one origin. Eligible operations retry only when you opt into a client retry policy.

| Method | HTTP / relative path | Response / retry eligibility |
| --- | --- | --- |
| `llmContext` | `GET /v1/llm/context` | json · eligible |
| `llmContextPost` | `POST /v1/llm/context` | json · no automatic retry |
| `answers` | `POST /v1/chat/completions` | json · no automatic retry |
| `answersStream` | `POST /v1/chat/completions` | SSE stream · no automatic retry |
| `search` | `GET /v1/web/search` | json · eligible |
| `searchPost` | `POST /v1/web/search` | json · no automatic retry |
| `localPois` | `GET /v1/local/pois` | json · eligible |
| `poiDescriptions` | `GET /v1/local/descriptions` | json · eligible |
| `rich` | `GET /v1/web/rich` | json · eligible |
| `news` | `GET /v1/news/search` | json · eligible |
| `newsPost` | `POST /v1/news/search` | json · no automatic retry |
| `videos` | `GET /v1/videos/search` | json · eligible |
| `videosPost` | `POST /v1/videos/search` | json · no automatic retry |
| `images` | `GET /v1/images/search` | json · eligible |
| `places` | `GET /v1/local/place_search` | json · eligible |
| `suggest` | `GET /v1/suggest/search` | json · eligible |
| `spellcheck` | `GET /v1/spellcheck/search` | json · eligible |

<a id="lifecycle"></a>

## Limits and operation lifecycle

- Pass `signal` and per-call `timeoutMs` on native request input when needed.
- Persist a returned job identifier before explicitly reading or polling the same job. Native clients do not automatically poll.
- SSE data is incremental provider event text. Parse and validate terminal or error events according to the provider contract; there is no reconnect or replay.
- Native operations may create, delete, ingest, or incur charges. A successful HTTP response is not proof that a remote job completed.

<a id="sources"></a>

## Official sources

Use the official reference for current schemas, account access, and operation-specific requirements.

- [Web Search documentation](https://api-dashboard.search.brave.com/app/documentation/web-search/get-started)

- [Native request and response reference](https://searchsdk.dev/docs/api/native-transport)
- [All providers](https://searchsdk.dev/docs/providers)