OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add brave/brave-search-skills --skill news-search
USE FOR news search. Returns news articles with title, URL, description, age, thumbnail, profile. Supports freshness and date range filtering, SafeSearch filter and Goggles for custom ranking.
npx skills add brave/brave-search-skills --skill news-search
Requires API Key: Get one at https://api.search.brave.com
Plan: Included in the Search plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe
Authentication: X-Subscription-Token: <API_KEY> header
Note: Both GET and POST are supported. POST is useful for long queries or complex Goggles.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
q | string | Yes | - | Search query (1-400 chars, max 50 words) |
country | string | No | US | Search country (2-letter country code or ALL) |
search_lang | string | No | en | Language preference (2+ char language code) |
ui_lang | string | No | en-US | UI language (e.g., "en-US") |
count | int | No | 20 | Number of results (1-50) |
offset | int | No | 0 | Page offset (0-9) |
safesearch | string | No | strict | Adult content filter (off/moderate/strict) |
freshness | string | No | - | Time filter (pd/pw/pm/py or date range) |
spellcheck | bool | No | true | Auto-correct query |
extra_snippets | bool | No | - | Up to 5 additional excerpts per result |
goggles | string or array | No | - | Custom ranking filter (URL or inline; repeat param for multiple) |
operators | bool | No | true | Apply search operators |
include_fetch_metadata | bool | No | false | Include fetch timestamps in results |
| Value | Description |
|---|---|
pd | Past day (24 hours) - ideal for breaking news |
pw | Past week (7 days) |
pm | Past month (31 days) |
py | Past year (365 days) |
YYYY-MM-DDtoYYYY-MM-DD | Custom date range |
| Field | Type | Description |
|---|---|---|
type | string | Always "news" |
query.original | string | The original search query |
query.altered | string? | Spellcheck-corrected query (if changed) |
query.cleaned | string? | Cleaned/normalized query from spellchecker |
query.spellcheck_off | bool? | Whether spellcheck was disabled |
query.show_strict_warning | bool? | True if strict safesearch blocked results |
query.search_operators | object? | Applied search operators |
query.search_operators.applied | bool | Whether operators were applied |
query.search_operators.cleaned_query | string? | Query after operator processing |
query.search_operators.sites | list[str]? | Domains from site: operators |
results[].type | string | Always "news_result" |
results[].title | string | Article title |
results[].url | string | Source URL of the article |
results[].description | string? | Article description/summary |
results[].age | string? | Human-readable age (e.g. "2 hours ago") |
results[].page_age | string? | Publication date from source (ISO datetime) |
results[].page_fetched | string? | When page was last fetched (ISO datetime) |
results[].fetched_content_timestamp | int? | Fetch timestamp (only with include_fetch_metadata=true) |
results[].meta_url.scheme | string? | URL protocol scheme |
results[].meta_url.netloc | string? | Network location |
results[].meta_url.hostname | string? | Lowercased domain name |
results[].meta_url.favicon | string? | Favicon URL |
results[].meta_url.path | string? | URL path |
results[].thumbnail.src | string | Served thumbnail URL |
results[].thumbnail.original | string? | Original thumbnail URL |
results[].extra_snippets | list[str]? | Up to 5 additional excerpts per result |
results[].profile.name | string? | Name of the site |
results[].profile.url | string? | The original URL where the profile is available |
results[].profile.long_name | string? | The long name of the site |
results[].profile.img | string? | The served image URL representing the profile |
Goggles let you re-rank news results — boost trusted outlets or suppress unwanted sources.
| Method | Example |
|---|---|
| Hosted | --data-urlencode "goggles=https://raw.githubusercontent.com/brave/goggles-quickstart/main/goggles/hacker_news.goggle" |
| Inline | --data-urlencode 'goggles=$discard\n$site=example.com' |
Hosted goggles must be on GitHub/GitLab, include
! name:,! description:,! author:headers, and be registered at https://search.brave.com/goggles/create. Inline rules need no registration.
Syntax: Rules start with $ + comma-separated options. Actions (pick one): discard, boost[=N], downrank[=N] — N is an integer 1–10. Site filter: site=DOMAIN. Example: $site=example.com,boost=3. Separate rules with \n (%0A).
Allow list: $discard\n$site=docs.python.org\n$site=developer.mozilla.org — Block list: $discard,site=pinterest.com\n$discard,site=quora.com
Resources: Discover · Syntax · Quickstart
Use search operators to refine results:
site:local-paper.com - Limit to specific news site"exact phrase" - Match exact phrase-exclude - Exclude termSet operators=false to disable operator parsing.
freshness=pd for the most recent articles on a topic.freshness=YYYY-MM-DDtoYYYY-MM-DD to find articles from specific time periods.country, search_lang, and ui_lang for cross-locale results.include_fetch_metadata=true for fetched_content_timestamp on each result.strictoffset (0-9) with countextra_snippets=truecurl -s "https://api.search.brave.com/res/v1/news/search" \
-H "Accept: application/json" \
-H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
-G \
--data-urlencode "q=cybersecurity" \
--data-urlencode "country=US" \
--data-urlencode "freshness=pd" \
--data-urlencode "count=20"curl -s "https://api.search.brave.com/res/v1/news/search" \
-H "Accept: application/json" \
-H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
-G \
--data-urlencode "q=climate summit" \
--data-urlencode "freshness=2026-01-01to2026-01-31"GET https://api.search.brave.com/res/v1/news/search
POST https://api.search.brave.com/res/v1/news/search{
"type": "news",
"query": {
"original": "space exploration"
},
"results": [
{
"type": "news_result",
"title": "New Developments in Space Exploration",
"url": "https://news.example.com/space-exploration",
"description": "Recent missions have advanced our understanding of...",
"age": "2 hours ago",
"page_age": "2026-01-15T14:30:00",
"page_fetched": "2026-01-15T15:00:00Z",
"meta_url": {
"scheme": "https",
"netloc": "news.example.com",
"hostname": "news.example.com",
"favicon": "https://imgs.search.brave.com/favicon/news.example.com",
"path": "/space-exploration"
},
"profile": {
"name": "Example Outlet",
"url": "https://news.example.com/space-exploration"
},
"thumbnail": {
"src": "https://imgs.search.brave.com/..."
}
}
]
}