YYYY-MM-DD. Default is the
latest that is available. Read more about API versioning.
schema:
anyOf:
- type: string
- type: 'null'
title: API version
description: >-
The API version to use. This is denoted by the
format YYYY-MM-DD. Default is the
latest that is available. Read more about API versioning.
deprecated: false
- name: cache-control
in: header
required: false
description: >-
Brave Search will return cached content by default.
To prevent caching set the Cache-Control header to
no-cache. This is currently done as
best effort.
schema:
anyOf:
- type: string
enum:
- no-cache
const: no-cache
title: CacheControl
- type: 'null'
title: Cache control
description: >-
Brave Search will return cached content by
default. To prevent caching set the Cache-Control
header to no-cache. This is currently
done as best effort.
deprecated: false
- name: user-agent
in: header
required: false
description: >-
The user agent originating the request. Brave search
can utilize the user agent to provide a different
experience depending on the device as described by the
string. The user agent should follow the commonly
used browser agent strings on each platform. For
more information on curating user agents, see RFC
9110.
schema:
anyOf:
- type: string
- type: 'null'
title: User agent
description: >-
The user agent originating the request. Brave
search can utilize the user agent to provide a
different experience depending on the device as
described by the string. The user agent should
follow the commonly used browser agent strings on
each platform. For more information on curating user
agents, see RFC
9110.
deprecated: false
examples:
Android:
value: >-
Mozilla/5.0 (Linux; Android 12) AppleWebKit/537.36 (KHTML, like
Gecko) Chrome/103.0.5060.71 Mobile Safari/537.36
description: Android
iOS:
value: >-
Mozilla/5.0 (iPhone; CPU iPhone OS 15_5 like Mac OS X)
AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/103.0.5060.63
Mobile/15E148 Safari/604.1
description: iOS
macOS:
value: >-
Mozilla/5.0 (Macintosh; Intel Mac OS X 12_4) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
description: macOS
Windows:
value: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36
(KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
description: Windows
- name: x-loc-city
in: header
required: false
description: The generic name of the client city
schema:
anyOf:
- type: string
- type: 'null'
description: The generic name of the client city
title: X-Loc-City
deprecated: false
examples:
City in USA:
value: Ann Arbor
- name: x-loc-country
in: header
required: false
description: >-
The two letter country code for the client’s
country. For a list of country
codes, see ISO 3166-1
alpha-2
schema:
anyOf:
- type: string
enum:
- AD
- AE
- AF
- AG
- AI
- AL
- AM
- AO
- AQ
- AR
- AS
- AT
- AU
- AW
- AX
- AZ
- BA
- BB
- BD
- BE
- BF
- BG
- BH
- BI
- BJ
- BL
- BM
- BN
- BO
- BQ
- BR
- BS
- BT
- BV
- BW
- BY
- BZ
- CA
- CC
- CD
- CF
- CG
- CH
- CI
- CK
- CL
- CM
- CN
- CO
- CR
- CU
- CV
- CW
- CX
- CY
- CZ
- DE
- DJ
- DK
- DM
- DO
- DZ
- EC
- EE
- EG
- EH
- ER
- ES
- ET
- FI
- FJ
- FK
- FM
- FO
- FR
- GA
- GB
- GD
- GE
- GF
- GG
- GH
- GI
- GL
- GM
- GN
- GP
- GQ
- GR
- GS
- GT
- GU
- GW
- GY
- HK
- HM
- HN
- HR
- HT
- HU
- ID
- IE
- IL
- IM
- IN
- IO
- IQ
- IR
- IS
- IT
- JE
- JM
- JO
- JP
- KE
- KG
- KH
- KI
- KM
- KN
- KP
- KR
- KW
- KY
- KZ
- LA
- LB
- LC
- LI
- LK
- LR
- LS
- LT
- LU
- LV
- LY
- MA
- MC
- MD
- ME
- MF
- MG
- MH
- MK
- ML
- MM
- MN
- MO
- MP
- MQ
- MR
- MS
- MT
- MU
- MV
- MW
- MX
- MY
- MZ
- NA
- NC
- NE
- NF
- NG
- NI
- NL
- 'NO'
- NP
- NR
- NU
- NZ
- OM
- PA
- PE
- PF
- PG
- PH
- PK
- PL
- PM
- PN
- PR
- PS
- PT
- PW
- PY
- QA
- RE
- RO
- RS
- RU
- RW
- SA
- SB
- SC
- SD
- SE
- SG
- SH
- SI
- SJ
- SK
- SL
- SM
- SN
- SO
- SR
- SS
- ST
- SV
- SX
- SY
- SZ
- TC
- TD
- TF
- TG
- TH
- TJ
- TK
- TL
- TM
- TN
- TO
- TR
- TT
- TV
- TW
- TZ
- UA
- UG
- UM
- US
- UY
- UZ
- VA
- VC
- VE
- VG
- VI
- VN
- VU
- WF
- WS
- YE
- YT
- ZA
- ZM
- ZW
title: Country
- type: 'null'
description: >-
The two letter country code for the client’s
country. For a list of country
codes, see ISO 3166-1
alpha-2
title: X-Loc-Country
deprecated: false
examples:
Country alpha-2 code:
value: US
- name: x-loc-lat
in: header
required: false
description: >-
The latitude of the client’s geographical location in
degrees, to provide relevant local results. The
latitude must be greater than or equal to -90.0
degrees and less than or equal to +90.0 degrees.
schema:
anyOf:
- type: number
maximum: 90
minimum: -90
- type: 'null'
description: >-
The latitude of the client’s geographical location in
degrees, to provide relevant local results. The
latitude must be greater than or equal to -90.0
degrees and less than or equal to +90.0 degrees.
title: X-Loc-Lat
deprecated: false
examples:
None: {}
- name: x-loc-long
in: header
required: false
description: >-
The longitude of the client’s geographical location in
degrees, to provide relevant local results. The
longitude must be greater than or equal to -180.0
and less than or equal to +180.0 degrees.
schema:
anyOf:
- type: number
maximum: 180
minimum: -180
- type: 'null'
description: >-
The longitude of the client’s geographical location in
degrees, to provide relevant local results. The
longitude must be greater than or equal to -180.0
and less than or equal to +180.0 degrees.
title: X-Loc-Long
deprecated: false
examples:
None: {}
- name: x-loc-postal-code
in: header
required: false
description: The client’s postal code
schema:
anyOf:
- type: string
- type: 'null'
description: The client’s postal code
title: X-Loc-Postal-Code
deprecated: false
examples:
Postal code in Ann Harbor, Michigan, US:
value: '48105'
- name: x-loc-state
in: header
required: false
description: >-
A code which could be up to three characters, that represent the
client’s state/region. The region is the first-level
subdivision (the broadest or least specific) of the
ISO 3166-2
code.
schema:
anyOf:
- type: string
- type: 'null'
description: >-
A code which could be up to three characters, that represent the
client’s state/region. The region is the
first-level subdivision (the broadest or least specific) of
the ISO 3166-2
code.
title: X-Loc-State
deprecated: false
examples:
Michigan State/Region code in USA:
value: MI
- name: x-loc-state-name
in: header
required: false
description: >-
The name of the client’s state/region. The region is
the first-level subdivision (the broadest or least specific) of
the ISO 3166-2 code.
schema:
anyOf:
- type: string
- type: 'null'
description: >-
The name of the client’s state/region. The region
is the first-level subdivision (the broadest or least specific) of
the ISO 3166-2
code.
title: X-Loc-State-Name
deprecated: false
examples:
Michigan generic state name in USA:
value: Michigan
requestBody:
required: true
description: ''
content:
application/json:
schema:
properties:
q:
type: string
maxLength: 600
minLength: 1
title: Q
description: >-
The user’s search query term. Query can not be empty.
Maximum of 600 characters and 75 words in the query.
country:
allOf:
- type: string
enum:
- AR
- AU
- AT
- BE
- BR
- CA
- CL
- DK
- FI
- FR
- DE
- GR
- HK
- IN
- ID
- IT
- JP
- KR
- MY
- MX
- NL
- NZ
- 'NO'
- CN
- PL
- PT
- PH
- RU
- SA
- ZA
- ES
- SE
- CH
- TW
- TR
- GB
- US
- ALL
title: SearchCountry
- default: US
description: >-
The search query country, where the results come from. The
country string is limited to 2 character country codes of
supported countries.
search_lang:
allOf:
- type: string
enum:
- ar
- eu
- bn
- bg
- ca
- zh-hans
- zh-hant
- hr
- cs
- da
- nl
- en
- en-gb
- et
- fi
- fr
- gl
- de
- el
- gu
- he
- hi
- hu
- is
- it
- ja
- jp
- kn
- ko
- lv
- lt
- ms
- ml
- mr
- nb
- pl
- pt-br
- pt-pt
- pa
- ro
- ru
- sr
- sk
- sl
- es
- sv
- ta
- te
- th
- tr
- uk
- vi
title: Language
- default: en
description: >-
The search language preference. The 2 or more character
language code for which the search results are provided.
count:
type: integer
maximum: 50
minimum: 1
title: Count
description: >-
The maximum number of search results considered to select
the LLM context data. The default is 20 and the maximum is
50.
default: 20
safesearch:
anyOf:
- type: string
enum:
- 'off'
- moderate
- strict
title: SafeSearch
- type: 'null'
title: Safe search
description: >-
Filters results for adult content. The following values are supported:
When not set, no filtering is applied — except for local
recall, which stays strict.
8192 and maximum is
32768.
default: 8192
maximum_number_of_snippets:
type: integer
maximum: 256
minimum: 1
title: Maximum Number Of Snippets
description: >-
Maximum number of different snippets (or chunks of text) to
include in LLM context. The default is 50 and
maximum is 256.
default: 50
context_threshold_mode:
anyOf:
- type: string
enum:
- disabled
- strict
- lenient
- balanced
title: SummarizerContextThresholdMode
- type: 'null'
description: >-
The mode to use to determine the threshold for including
content in context.
maximum_number_of_tokens_per_url:
type: integer
maximum: 8192
minimum: 512
title: Maximum Number Of Tokens Per Url
description: >-
Maximum number of tokens to include per URL. The default is
4096 and maximum is 8192.
default: 4096
maximum_number_of_snippets_per_url:
type: integer
maximum: 100
minimum: 1
title: Maximum Number Of Snippets Per Url
description: >-
Maximum number of snippets to include per URL. The default
is 50 and maximum is 100.
default: 50
goggles:
anyOf:
- type: string
- items:
type: string
type: array
- type: 'null'
title: Goggles
description: >-
Goggles act as a custom re-ranking on top of Brave’s search
index. The parameter supports both a url where the Goggle is
hosted or the definition of the Goggle. For more details,
see the Goggles
documentation. The parameter can be a single Goggle or a
list of up to 3 Goggles.
freshness:
type: string
title: Freshness
description: >-
Filters search results by page age. The age of a page is determined by the most relevant date reported by the content, such as its published or last modified date. The following values are supported:
2022-04-01to2022-07-30.X-Loc-Lat with X-Loc-Long, or
X-Loc-City).
enable_source_metadata:
type: boolean
title: Enable Source Metadata
description: >-
Enable source metadata enrichment (site_name, favicon,
thumbnail, description, fetched_content_timestamp) in the
sources attribute of the response.
default: false
type: object
required:
- q
title: LLMContextParameters
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: >-
#/components/schemas/ResponseE3Baaa015480_LLMContextAPIResponse
default:
content:
application/json:
schema: {}
description: >-
Error response; upstream passthrough responses may use provider
formats
components:
schemas:
ResponseE3Baaa015480_LLMContextAPIResponse:
properties:
grounding:
$ref: '#/components/schemas/ResponseE3Baaa015480_LLMContext'
default:
generic: []
map: []
sources:
additionalProperties:
$ref: '#/components/schemas/ResponseE3Baaa015480_Source'
type: object
title: Sources
description: Metadata for all referenced URLs, keyed by URL.
default: {}
type: object
title: LLMContextAPIResponse
description: Response model for the LLM Context API (/v1/llm/context).
ResponseE3Baaa015480_LLMContext:
properties:
generic:
items:
$ref: '#/components/schemas/ResponseE3Baaa015480_LLMContextItem'
type: array
title: Generic
description: Array of LLM context items with extracted web content.
default: []
poi:
anyOf:
- $ref: '#/components/schemas/ResponseE3Baaa015480_LLMContextPOIItem'
- type: 'null'
description: >-
Point of interest data. When enable_local is enabled,
the response may include POI data.
map:
items:
$ref: '#/components/schemas/ResponseE3Baaa015480_LLMContextMapItem'
type: array
title: Map
description: >-
Map/place results. When enable_local is enabled, the
response may include map data.
default: []
type: object
title: LLMContext
description: Container for all LLM context content by type.
ResponseE3Baaa015480_Source:
properties:
title:
type: string
title: Title
description: The page title.
default: ''
hostname:
type: string
title: Hostname
description: The source hostname.
default: ''
age:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Age
description: >-
The page’s date rendered four ways, in fixed positions: full date,
YYYY-MM-DD, relative age, and an ISO 8601 timestamp.
Empty when the page has no known date.
site_name:
anyOf:
- type: string
- type: 'null'
title: Site Name
description: The site name (e.g. ‘Wikipedia’).
favicon:
anyOf:
- type: string
- type: 'null'
title: Favicon
description: URL to the site’s favicon image.
thumbnail:
anyOf:
- $ref: >-
#/components/schemas/ResponseE3Baaa015480_snakepit__models__search_api__specs__atomic__Thumbnail
- type: 'null'
description: >-
Page thumbnail: src is the proxied URL (ready to
serve); original is the raw upstream URL.
robotstxt_status:
anyOf:
- type: string
enum:
- allow
- disallow
- unknown
- type: 'null'
title: Robotstxt Status
description: >-
Robots.txt status for the requested user-agent: allow, disallow, or
unknown.
snippet:
anyOf:
- type: string
- type: 'null'
title: Snippet
description: The most query-relevant passage of the source page.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: >-
The page’s own description, independent of the query (unlike
snippet). Requires enable_source_metadata.
fetched_content_timestamp:
anyOf:
- type: integer
- type: 'null'
title: Fetched Content Timestamp
description: >-
Unix seconds of the index’s last fetch of this page. Requires
enable_source_metadata.
type: object
title: Source
description: Minimal metadata for a referenced source URL.
ResponseE3Baaa015480_LLMContextItem:
properties:
url:
type: string
title: Url
description: The source URL.
default: ''
title:
type: string
title: Title
description: The page title.
default: ''
snippets:
items:
type: string
type: array
title: Snippets
description: >-
Extracted text chunks from the page that are picked for their
relevance to the query.
default: []
type: object
title: LLMContextItem
description: >-
A single LLM context item with URL, title, snippets, and optional last
modified dates.
ResponseE3Baaa015480_LLMContextPOIItem:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the point of interest.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: The URL of the point of interest.
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: The title of the point of interest.
snippets:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Snippets
description: The snippets about the point of interest.
type: object
title: LLMContextPOIItem
description: >-
A point of interest item returned in the poi array for
local recall queries.
ResponseE3Baaa015480_LLMContextMapItem:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the place.
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: The URL of the place.
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: The title of the place.
snippets:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Snippets
description: The snippets about the place.
type: object
title: LLMContextMapItem
description: >-
A map/place item returned in the map array for local recall
queries.
ResponseE3Baaa015480_snakepit__models__search_api__specs__atomic__Thumbnail:
properties:
src:
type: string
title: Src
description: The served URL of the picture thumbnail.
alt:
anyOf:
- type: string
- type: 'null'
title: Alt
description: The alt text for the thumbnail image.
height:
anyOf:
- type: integer
- type: 'null'
title: Height
description: The height of the thumbnail.
width:
anyOf:
- type: integer
- type: 'null'
title: Width
description: The width of the thumbnail.
bg_color:
anyOf:
- type: string
- type: 'null'
title: Bg Color
description: The background color of the thumbnail.
original:
anyOf:
- type: string
- type: 'null'
title: Original
description: The original URL of the image.
logo:
anyOf:
- type: boolean
- type: 'null'
title: Logo
description: Whether the thumbnail is a logo.
duplicated:
anyOf:
- type: boolean
- type: 'null'
title: Duplicated
description: Whether the thumbnail is a duplicate.
theme:
anyOf:
- type: string
- type: 'null'
title: Theme
description: The theme of the thumbnail (e.g., light or dark).
type: object
required:
- src
title: Thumbnail
description: Aggregated details representing a picture thumbnail.
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.