🌐 Web Search

Perform real-time web searches powered by the Brave Search API. Returns structured results including title, URL, description, and publication date for each result. Optionally filter by freshness (last day/week/month/year), country, and language. Also surfaces a news panel and knowledge infobox when available — ideal for AI agents that need live web intelligence.

Request Body

Parameter	Type	Required	Description	Default
`query`	string	required	Search query string	—
`count`	number	optional	Number of web results to return (1–20)	`5`
`freshness`	string	optional	Filter by recency: pd (past day), pw (past week), pm (past month), py (past year), or YYYY-MM-DDtoYYYY-MM-DD range	—
`country`	string	optional	2-letter country code for regional results (e.g. US, DE, JP)	—
`language`	string	optional	ISO language code for results (e.g. en, de, fr, ja)	—

Response Fields

Field	Type	Description
`query`	string	The search query that was executed
`totalResults`	number	Total estimated results from Brave
`results`	array	Web results: [{ title, url, description, published, siteName }]
`news`	array	Up to 3 news results when available: [{ title, url, description, published, source }]
`infobox`	object \| null	Knowledge panel when available: { title, description, url }

Code Examples

cURL

bash

curl -X POST https://sparkforge.sh/api/search \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <x402-payment-token>" \
  -d '{
    "query": "Bitcoin ETF inflows 2026",
    "count": 5,
    "freshness": "pw"
  }'

Python

python

import requests

response = requests.post(
    "https://sparkforge.sh/api/search",
    headers={
        "Content-Type": "application/json",
        "X-PAYMENT": "<x402-payment-token>"
    },
    json={
        "query": "SparkForge x402 API",
        "count": 5,
        "freshness": "pm",
        "country": "US"
    }
)

data = response.json()
print(f"Found {data['totalResults']} results")
for r in data["results"]:
    print(f"  • {r['title']}")
    print(f"    {r['url']}")

TypeScript / Node.js

typescript

import { wrapFetchWithPayment } from "@x402/fetch";

const fetch402 = wrapFetchWithPayment(fetch, wallet);

const res = await fetch402("https://sparkforge.sh/api/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "Bitcoin ETF inflows 2026",
    count: 5,
    freshness: "pw",
  }),
});

const { results, news, infobox } = await res.json();
results.forEach((r: any) => console.log(r.title, r.url));

Example Response

json

{
  "query": "Bitcoin ETF inflows 2026",
  "totalResults": 42300,
  "results": [
    {
      "title": "Bitcoin ETFs See Record $500M Inflow Week",
      "url": "https://coindesk.com/markets/2026/02/bitcoin-etf-inflows",
      "description": "BlackRock's iShares Bitcoin Trust led the week with $310M in net inflows...",
      "published": "3 days ago",
      "siteName": "coindesk.com"
    },
    {
      "title": "Institutional BTC Demand Surges in Q1 2026",
      "url": "https://cointelegraph.com/news/institutional-btc-demand-q1-2026",
      "description": "Spot Bitcoin ETFs collectively attracted over $2B in Q1 2026...",
      "published": "1 week ago",
      "siteName": "cointelegraph.com"
    }
  ],
  "news": [
    {
      "title": "BTC ETF Inflows Hit New Weekly Record",
      "url": "https://decrypt.co/...",
      "description": "Weekly inflows surpassed $500M for the first time...",
      "published": "2 days ago",
      "source": "decrypt.co"
    }
  ],
  "infobox": null
}

💳 Payment via x402

This endpoint costs $0.005 per call, paid in USDC on Base, Polygon, or Solana. Use the @x402/fetch library to handle payments automatically, or implement the x402 handshake manually.

bash

# Free demo mode (no payment)
curl https://sparkforge.sh/api/search?demo=true

# Or try via MCP (Claude Desktop, Cursor, Windsurf)
# Add to mcp config: { "url": "https://sparkforge.sh/api/mcp" }

←

Domain & SSL Checker