Search

POST /v1/search runs a SERP query and returns ranked snippets plus a short synthesised answer in well under two seconds.

There is no depth selector — the gateway runs a single tuned instant flow. Semantic intent filters (topic, time range, domains) are still honoured.

Quick example

from brime import Brime

client = Brime()
result = client.search(
    query="Apple Q4 2025 earnings highlights",
    max_results=5,
)
print(result.answer)
for r in result.results:
    print(f"- {r.title}  {r.url}")

import { Brime } from "@brime-ai/brime";

const client = new Brime();
const result = await client.search({
  query: "Apple Q4 2025 earnings highlights",
  max_results: 5,
});
console.log(result.answer);
for (const r of result.results) {
  console.log(`- ${r.title}  ${r.url}`);
}

curl https://api.brime.dev/v1/search \
  -H "Authorization: Bearer $BRIME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Apple Q4 2025 earnings highlights",
    "max_results": 5
  }'

Request

Field	Type	Default	Description
`query`	string	required	Natural-language search query (1–1,000 chars).
`topic`	`"general" \| "news" \| "finance"`	`"general"`	Recency hint. `news` clamps cache TTL to 30 s.
`max_results`	integer	`5`	1–20.
`time_range`	`"day" \| "week" \| "month" \| "year"`	—	Restrict to recency window.
`start_date`	`YYYY-MM-DD`	—	Lower bound on `published_date`.
`end_date`	`YYYY-MM-DD`	—	Upper bound on `published_date`.
`include_answer`	bool	`true`	Return synthesised answer string.
`include_images`	bool	`false`	Reserved.
`domains`	string[]	—	Domain allow-list.
`exclude_domains`	string[]	—	Domain deny-list.

The historical depth field (and LLM tuning knobs like model, token_mode, ranking) are accepted but ignored — the gateway always runs the instant tier.

Latency & cost

Single tier: ~500 ms p50, 0.5 credits per call. Errors are not charged.

Response

{
  "query": "Apple Q4 2025 earnings highlights",
  "answer": "Apple reported $98.4B in Q4 2025 revenue, up 6% YoY, led by Services and Vision Pro 2 launch quarter sales...",
  "results": [
    {
      "title": "Apple Q4 2025 Earnings — Reuters",
      "url": "https://www.reuters.com/technology/apple-q4-2025-results",
      "content": "Apple's fiscal Q4 2025 revenue rose 6% to $98.4B, beating consensus by $1.2B...",
      "score": 0.92,
      "published_date": "2025-10-30"
    }
  ],
  "request_id": "req_01J...",
  "credits_used": 0.5,
  "latency_ms": 643
}

Field	Type	Notes
`query`	string	Echoes the request.
`answer`	string \| null	LLM-synthesised answer; `null` when no results.
`results`	`SearchResultItem[]`	Top-`max_results` ranked.
`request_id`	string	Globally unique; useful for audit and refund tickets.
`credits_used`	number	This call's debit.
`latency_ms`	number	Wall-clock from receive to send.

`SearchResultItem`

Field	Type	Notes
`title`	string	Page title.
`url`	string	Canonical URL.
`content`	string	SERP snippet.
`score`	number \| null	SERP relevance score (when available).
`published_date`	string \| null	ISO-8601 if known, else null.

Edge cases

No results: results: [], answer: null. We don't error.
Empty query: 400 invalid_request.
max_results > 20: silently clamped to 20.
Conflicting filters (e.g., time_range=week + start_date 2 years ago): start_date/end_date win.

Errors

Status	`code`	Meaning
400	`invalid_request`	Malformed body or empty query.
401	`unauthorized`	Missing/revoked API key.
429	`rate_limited`	Per-key budget hit.
502	`upstream_error`	SERP or LLM provider degraded.

See Errors for the full catalog and retry guidance.