Skip to main content
POST
Search the web

Authorizations

Authorization
string
header
required

An API key from the dashboard, sk_live_…, sent as Authorization: Bearer sk_live_….

Body

application/json
query
string
required

What to search for, in natural language. Keyword engines (Brave, Serper) receive it as typed; neural engines (Exa, Parallel) interpret it semantically.

Minimum string length: 1
provider
enum<string>

Which engine serves the request. auto (default) picks the first configured provider in Helve's priority order. fusion fans out to a panel of engines and merges their top picks by consensus; see the Fusion guide.

Available options:
exa,
parallel,
tavily,
brave,
serper,
firecrawl,
linkup,
valyu,
jina,
octen,
perplexity,
auto,
fusion
max_results
integer

Number of results to return, 1–100. Default 10. Engines with a lower ceiling (Tavily and Brave stop at 20) are capped with a param_approximated warning. With fusion this sizes each member's list, not the merged one.

Required range: 1 <= x <= 100
mode
enum<string>

Speed/quality trade-off, mapped to each engine's tiers (Exa instant/fast/auto/deep, Parallel turbo/fast/basic/advanced, Tavily ultra-fast/fast/basic/advanced). Single-tier engines ignore it with a warning. Default: the engine's own default tier.

Available options:
instant,
fast,
balanced,
deep
include_domains
string[]

Only return pages from these domains. Native on most engines; rewritten into site: operators on Brave and Serper.

Minimum string length: 1
exclude_domains
string[]

Never return pages from these domains. Native on most engines; rewritten into -site: operators on Brave and Serper.

Minimum string length: 1
published_after
string

Only pages published on or after this date, YYYY-MM-DD. Mutually exclusive with freshness.

Pattern: ^\d{4}-\d{2}-\d{2}$
published_before
string

Only pages published on or before this date, YYYY-MM-DD. Mutually exclusive with freshness.

Pattern: ^\d{4}-\d{2}-\d{2}$
freshness
enum<string>

Shorthand for a rolling publication window ending now. Mutually exclusive with published_after / published_before.

Available options:
day,
week,
month,
year
content
object

What text to return for each result. Every engine returns snippets; full text and summaries depend on the engine.

locale
object

Bias results toward a country and language. Native on Brave, Serper, and Tavily.

category
enum<string>

Content category. news maps to the engine's news index where one exists; company, people, and research are native on Exa and approximated elsewhere.

Available options:
general,
news,
company,
people,
research

Adult-content filtering. Native on Brave and Serper; ignored with a warning elsewhere.

Available options:
off,
moderate,
strict
offset
integer

Skip this many results for pagination. Native on Brave and Serper only; other engines ignore it with a warning.

Required range: x >= 0
strict
boolean

When true, any parameter the serving engine cannot honour is a 400 instead of a warning. Not allowed with fusion. Default false.

provider_options
object

Escape hatch for provider-native parameters. Each key is a provider id; its value is merged into that provider's request unchanged. Helve never inspects these, except fusion, which is Helve's own and typed.

Response

Search results

id
string
required

Helve's id for this search, srch_….

provider
enum<string>
required

The engine that served the request, resolved from auto, or fusion.

Available options:
exa,
parallel,
tavily,
brave,
serper,
firecrawl,
linkup,
valyu,
jina,
octen,
perplexity,
fusion
results
object[]
required
warnings
object[]
required

How the request was adjusted for the serving engine. Empty when it was honoured exactly.

usage
object
required
latency_ms
number
required

Wall-clock time Helve spent on the request. With fusion, roughly the slowest member.