Brave Search

AI Search

API for AI-generated answers backed by real-time web search and verifiable sources

Request Body required

messages object[] required

The conversation so far. Exactly one user message is supported, e.g. [{"role": "user", "content": "Explain quantum computing"}].

messages.role "user"

Default: "user"

messages.content string required

model enum<string>

Model ID used to generate the response.

Default: "brave-pro"

Available options: brave-probrave

max_completion_tokens integer nullable

metadata object nullable

Accepted for OpenAI SDK compatibility and currently ignored: the pairs are not stored or returned.

seed integer nullable

Accepted for OpenAI SDK compatibility and currently ignored: answers are not reproducible.

stream boolean

Default: true

web_search_options object nullable

web_search_options.search_context_size enum<string> nullable

Available options: lowmediumhigh

web_search_options.user_location object nullable

web_search_options.user_location.approximate object required

web_search_options.user_location.type "approximate"

Default: "approximate"

country string

Default: "us"

language string

Default: "en"

safesearch string

Default: "moderate"

enable_entities boolean

Whether to include inline entity tags in the answer. Requires stream=true and is not supported in research mode.

Default: false

enable_citations boolean

Whether to include inline citation tags in the answer. Requires stream=true and is not supported in research mode.

Default: false

enable_research boolean

Whether to answer with iterative deep research instead of a single search. Requires stream=true.

Default: false

research_allow_thinking boolean

Accepted for compatibility. Ignored by the mixer engine behind this API, which always runs research with extended thinking off.

Default: true

research_maximum_number_of_tokens_per_query integer

Maximum number of tokens to gather per research query.

Min: 1024 Max: 16384 Default: 8192

research_maximum_number_of_queries integer

Maximum number of search queries research mode may issue in total.

Min: 1 Max: 50 Default: 20

research_maximum_number_of_iterations integer

Maximum number of research iterations.

Min: 1 Max: 5 Default: 4

research_maximum_number_of_seconds integer

Time budget for research, in seconds.

Min: 1 Max: 300 Default: 180

research_maximum_number_of_results_per_query integer

Maximum number of search results to consider per research query.

Min: 1 Max: 60 Default: 30

Responses

200 Successful Response

model enum<string>

Default: "brave-pro"

Available options: brave-probrave

system_fingerprint string nullable

choices object[] required

choices.delta object required

choices.delta.role "assistant"

Default: "assistant"

choices.delta.content string required

choices.finish_reason enum<string> nullable

Available options: stoplength

created integer required

id string required

object "chat.completion.chunk"

Default: "chat.completion.chunk"

usage object nullable

usage.completion_tokens integer required

usage.prompt_tokens integer required

usage.total_tokens integer required

usage.completion_tokens_details object nullable

usage.completion_tokens_details.reasoning_tokens integer nullable

400 Bad Request

type string

Default: "ErrorResponse"

error object required

error.id string required

A unique identifier for this particular occurrence of the problem.

error.status integer required

The HTTP status code applicable to this problem, expressed as a string value.

error.detail string nullable

Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

error.meta object nullable

A meta object containing non-standard meta-information about the error.

error.code enum<string> required

An application-specific error code, expressed as a string value.

Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED

time integer

Default: 0

402 Payment Required

type string

Default: "ErrorResponse"

error object required

error.id string required

A unique identifier for this particular occurrence of the problem.

error.status integer required

The HTTP status code applicable to this problem, expressed as a string value.

error.detail string nullable

Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

error.meta object nullable

A meta object containing non-standard meta-information about the error.

error.code enum<string> required

An application-specific error code, expressed as a string value.

Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED

time integer

Default: 0

403 Forbidden

type string

Default: "ErrorResponse"

error object required

error.id string required

A unique identifier for this particular occurrence of the problem.

error.status integer required

The HTTP status code applicable to this problem, expressed as a string value.

error.detail string nullable

Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

error.meta object nullable

A meta object containing non-standard meta-information about the error.

error.code enum<string> required

An application-specific error code, expressed as a string value.

Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED

time integer

Default: 0

404 Not Found

type string

Default: "ErrorResponse"

error object required

error.id string required

A unique identifier for this particular occurrence of the problem.

error.status integer required

The HTTP status code applicable to this problem, expressed as a string value.

error.detail string nullable

Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

error.meta object nullable

A meta object containing non-standard meta-information about the error.

error.code enum<string> required

An application-specific error code, expressed as a string value.

Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED

time integer

Default: 0

422 Unprocessable Entity

type string

Default: "ErrorResponse"

error object required

error.id string required

A unique identifier for this particular occurrence of the problem.

error.status integer required

The HTTP status code applicable to this problem, expressed as a string value.

error.detail string nullable

Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

error.meta object nullable

A meta object containing non-standard meta-information about the error.

error.code enum<string> required

An application-specific error code, expressed as a string value.

Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED

time integer

Default: 0

429 Too Many Requests

type string

Default: "ErrorResponse"

error object required

error.id string required

A unique identifier for this particular occurrence of the problem.

error.status integer required

The HTTP status code applicable to this problem, expressed as a string value.

error.detail string nullable

Explanation specific to this occurrence of the problem. Like title, this field’s value can be localized.

error.meta object nullable

A meta object containing non-standard meta-information about the error.

error.code enum<string> required

An application-specific error code, expressed as a string value.

Available options: INTERNALQUOTA_LIMITEDRATE_LIMITED

time integer

Default: 0

curl -X POST -s --compressed "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "Content-Type: application/json" \
  -d '{"stream": false, "messages": [{"role": "user", "content": "What is the second highest mountain?"}]}' \
  -H "x-subscription-token: <YOUR_BRAVE_SEARCH_API_KEY>"

from openai import AsyncOpenAI
import asyncio

client = AsyncOpenAI(
    api_key="<YOUR_BRAVE_SEARCH_API_KEY>",
    base_url="https://api.search.brave.com/res/v1",
)

async def stream_answer():
    async for chunk in await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "Explain quantum computing",
            }
        ],
        model="brave",
        stream=True,
    ):
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)

asyncio.run(stream_answer())