/answers

name: answers
description: "USE FOR AI-grounded answers via OpenAI-compatible /chat/completions. Two modes: single-search (fast) or deep research (enable_research=true, thorough multi-search). Streaming/blocking. Citations."

Answers — AI Grounding

> **Requires API Key**: Get one at https://api.search.brave.com > > **Plan**: Included in the **Answers** plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

When to Use

| Use Case | Skill | Why | |--|--|--| | Quick factual answer (raw context) | `llm-context` | Single search, returns raw context for YOUR LLM | | Fast AI answer with citations | **`answers`** (single-search) | streaming, citations | | Thorough multi-search deep research | **`answers`** (research mode) | Iterative deep research, synthesized cited answer |

**This endpoint** (`/res/v1/chat/completions`) supports two modes:

• **Single-search** (default): Fast AI-grounded answer from a single search. Supports `enable_citations`.
• **Research** (`enable_research=true`): Multi-iteration deep research with progress events and synthesized cited answer.

Quick Start (cURL)

Blocking (Single-Search)

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "How does the James Webb Space Telescope work?"}],
    "stream": false
  }'

Streaming with Citations (Single-Search)

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "What are recent breakthroughs in fusion energy?"}],
    "stream": true,
    "enable_citations": true
  }'

Research Mode

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "Compare quantum computing approaches"}],
    "stream": true,
    "enable_research": true,
    "research_maximum_number_of_iterations": 3,
    "research_maximum_number_of_seconds": 120
  }'

Endpoint

POST https://api.search.brave.com/res/v1/chat/completions

**Authentication**: `X-Subscription-Token: <API_KEY>` header (or `Authorization: Bearer <API_KEY>`)

**SDK Compatible**: Works with OpenAI SDK via `base_url="https://api.search.brave.com/res/v1"`

Two Modes

| Feature | Single-Search (default) | Research (`enable_research=true`) | |--|--|--| | Speed | Fast | Slow | | Searches | 1 | Multiple (iterative) | | Streaming | Optional (`stream=true/false`) | **Required** (`stream=true`) | | Citations | `enable_citations=true` (streaming only) | Built-in (in `<answer>` tag) | | Progress events | No | Yes (`<progress>` tags) | | Blocking response | Yes (`stream=false`) | No |

Parameters

Standard Parameters

| Parameter | Type | Required | Default | Description | |--|--|--|--|--| | `messages` | array | **Yes** | - | Single user message (exactly 1 message) | | `stream` | bool | No | true | Enable SSE streaming | | `country` | string | No | "US" | Search country (2-letter country code or `ALL`) | | `language` | string | No | "en" | Response language | | `safesearch` | string | No | "moderate" | Search safety level (`off`, `moderate`, `strict`) | | `max_completion_tokens` | int | No | null | Upper bound on completion tokens | | `enable_citations` | bool | No | false | Include inline citation tags (single-search streaming only) | | `web_search_options` | object | No | null | OpenAI-compatible; `search_context_size`: `low`, `medium`, `high` |

Research Parameters

| Parameter | Type | Required | Default | Description | |--|--|--|--|--| | `enable_research` | bool | No | `false` | **Enable research mode** | | `research_allow_thinking` | bool | No | `true` | Enable extended thinking | | `research_maximum_number_of_tokens_per_query` | int | No | `8192` | Max tokens per query (1024-16384) | | `research_maximum_number_of_queries` | int | No | `20` | Max total search queries (1-50) | | `research_maximum_number_of_iterations` | int | No | `4` | Max research iterations (1-5) | | `research_maximum_number_of_seconds` | int | No | `180` | Time budget in seconds (1-300) | | `research_maximum_number_of_results_per_query` | int | No | `60` | Results per search query (1-60) |

Constraints (IMPORTANT)

| Constraint | Error | |--|--| | `enable_research=true` requires `stream=true` | "Blocking response doesn't support 'enable_research' option" | | `enable_research=true` incompatible with `enable_citations=true` | "Research mode doesn't support 'enable_citations' option" | | `enable_citations=true` requires `stream=true` | "Blocking response doesn't support 'enable_citations' option" |

OpenAI SDK Usage

Blocking (Single-Search)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.search.brave.com/res/v1",
    api_key="your-brave-api-key",
)

response = client.chat.completions.create(
    model="brave",
    messages=[{"role": "user", "content": "How does the James Webb Space Telescope work?"}],
    stream=False,
)
print(response.choices[0].message.content)

Streaming with Citations (Single-Search)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.search.brave.com/res/v1",
    api_key="your-brave-api-key",
)

stream = client.chat.completions.create(
    model="brave",
    messages=[{"role": "user", "content": "What are the current trends in renewable energy?"}],
    stream=True,
    extra_body={"enable_citations": True}
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Research Mode

from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.search