> ## Documentation Index > Fetch the complete documentation index at: https://docs.helve.dev/llms.txt > Use this file to discover all available pages before exploring further. # Search the web > One request shape across every search engine Helve fronts. Pick an engine with `provider`, leave it on `auto`, or set `fusion` to merge a panel's top picks. Parameters the serving engine cannot express are approximated or dropped and reported in `warnings`; set `strict` to make that an error instead. The response always includes what the request cost. ## OpenAPI ````yaml openapi.json POST /v1/search openapi: 3.1.0 info: title: Helve API version: 1.0.0 description: >- One key, one request shape, one bill for the tools your software calls: web search across eleven engines, page extraction across nine, and transcription across three. Every response says which provider served it, how the request was adjusted for that provider, and what it cost. servers: - url: https://helve.dev description: Production security: - bearerAuth: [] tags: - name: Search description: >- Web search with one schema across Exa, Parallel, Tavily, Brave, Serper, Firecrawl, Linkup, Valyu, Jina, Octen, Perplexity, and the `fusion` panel. - name: Extract description: Fetch and clean pages by URL. - name: Transcription description: >- Durable speech-to-text jobs across AssemblyAI, Deepgram, and ElevenLabs. Submit a recording, poll the job. paths: /v1/search: post: tags: - Search summary: Search the web description: >- One request shape across every search engine Helve fronts. Pick an engine with `provider`, leave it on `auto`, or set `fusion` to merge a panel's top picks. Parameters the serving engine cannot express are approximated or dropped and reported in `warnings`; set `strict` to make that an error instead. The response always includes what the request cost. operationId: search requestBody: required: true content: application/json: example: query: latest research on speculative decoding provider: fusion max_results: 5 freshness: month schema: type: object properties: query: type: string minLength: 1 description: >- What to search for, in natural language. Keyword engines (Brave, Serper) receive it as typed; neural engines (Exa, Parallel) interpret it semantically. provider: type: string enum: - exa - parallel - tavily - brave - serper - firecrawl - linkup - valyu - jina - octen - perplexity - auto - fusion description: >- 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. max_results: type: integer minimum: 1 maximum: 100 description: >- 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. mode: type: string enum: - instant - fast - balanced - deep description: >- 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. include_domains: type: array items: type: string minLength: 1 description: >- Only return pages from these domains. Native on most engines; rewritten into `site:` operators on Brave and Serper. exclude_domains: type: array items: type: string minLength: 1 description: >- Never return pages from these domains. Native on most engines; rewritten into `-site:` operators on Brave and Serper. published_after: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Only pages published on or after this date, `YYYY-MM-DD`. Mutually exclusive with `freshness`. published_before: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Only pages published on or before this date, `YYYY-MM-DD`. Mutually exclusive with `freshness`. freshness: type: string enum: - day - week - month - year description: >- Shorthand for a rolling publication window ending now. Mutually exclusive with `published_after` / `published_before`. content: type: object properties: snippets: type: object properties: max_per_result: type: integer minimum: 1 description: Cap on the number of snippets per result. max_chars_per_snippet: type: integer minimum: 1 description: Cap on the length of each snippet, in characters. additionalProperties: false description: Controls the relevant excerpts returned in `snippets`. full_text: type: boolean description: >- Return the full page text in `full_text`. Native on Exa and Tavily; other engines ignore it with a warning. summary: type: boolean description: >- Return a per-result summary in `summary`. Native on Exa only. additionalProperties: false description: >- What text to return for each result. Every engine returns snippets; full text and summaries depend on the engine. locale: type: object properties: country: type: string pattern: ^[a-zA-Z]{2}$ description: ISO 3166-1 alpha-2 country code, e.g. `us`. language: type: string pattern: ^[a-zA-Z]{2}$ description: ISO 639-1 language code, e.g. `en`. additionalProperties: false description: >- Bias results toward a country and language. Native on Brave, Serper, and Tavily. category: type: string enum: - general - news - company - people - research description: >- Content category. `news` maps to the engine's news index where one exists; `company`, `people`, and `research` are native on Exa and approximated elsewhere. safe_search: type: string enum: - 'off' - moderate - strict description: >- Adult-content filtering. Native on Brave and Serper; ignored with a warning elsewhere. offset: type: integer minimum: 0 description: >- Skip this many results for pagination. Native on Brave and Serper only; other engines ignore it with a warning. strict: type: boolean description: >- When true, any parameter the serving engine cannot honour is a 400 instead of a warning. Not allowed with `fusion`. Default false. provider_options: type: object properties: exa: type: object additionalProperties: nullable: true description: >- Passed verbatim to Exa when it serves the request; ignored by every other provider. parallel: type: object additionalProperties: nullable: true description: >- Passed verbatim to Parallel when it serves the request; ignored by every other provider. tavily: type: object additionalProperties: nullable: true description: >- Passed verbatim to Tavily when it serves the request; ignored by every other provider. brave: type: object additionalProperties: nullable: true description: >- Passed verbatim to Brave when it serves the request; ignored by every other provider. serper: type: object additionalProperties: nullable: true description: >- Passed verbatim to Serper when it serves the request; ignored by every other provider. firecrawl: type: object additionalProperties: nullable: true description: >- Passed verbatim to Firecrawl when it serves the request; ignored by every other provider. linkup: type: object additionalProperties: nullable: true description: >- Passed verbatim to Linkup when it serves the request; ignored by every other provider. octen: type: object additionalProperties: nullable: true description: >- Passed verbatim to Octen when it serves the request; ignored by every other provider. perplexity: type: object additionalProperties: nullable: true description: >- Passed verbatim to Perplexity when it serves the request; ignored by every other provider. valyu: type: object additionalProperties: nullable: true description: >- Passed verbatim to Valyu when it serves the request; ignored by every other provider. jina: type: object additionalProperties: nullable: true description: >- Passed verbatim to Jina when it serves the request; ignored by every other provider. fusion: type: object properties: providers: type: array items: type: string enum: - exa - parallel - tavily - brave - serper - firecrawl - linkup - valyu - jina - octen - perplexity minItems: 2 description: >- Which engines to fan out to (at least 2). Default: the curated panel of exa, parallel, octen, and perplexity, intersected with the providers configured on your deployment. timeout_ms: type: integer minimum: 500 maximum: 30000 description: >- Per-engine time budget in milliseconds. A member that is still running at the deadline is retried once, then dropped with a `results_post_filtered` warning. Default 10000. top_k: type: integer minimum: 1 maximum: 100 description: >- How many of each engine's top results are always kept. Deeper pages survive only when at least two engines returned them. Default 3; 10 or more approximates the full union. additionalProperties: false description: >- Panel controls, honoured only when `provider` is `fusion`. additionalProperties: false description: >- 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. required: - query additionalProperties: false responses: '200': description: Search results content: application/json: schema: type: object properties: id: type: string description: Helve's id for this search, `srch_…`. provider: type: string enum: - exa - parallel - tavily - brave - serper - firecrawl - linkup - valyu - jina - octen - perplexity - fusion description: >- The engine that served the request, resolved from `auto`, or `fusion`. results: type: array items: type: object properties: id: type: string description: >- Helve's id for this result, stable per URL within a search. url: type: string title: type: string nullable: true snippets: type: array items: type: string description: >- Relevant excerpts from the page. Every engine returns these: Exa highlights, Parallel excerpts, Tavily content, Brave descriptions, Serper snippets. full_text: type: string description: >- The full page text, when `content.full_text` was requested and the engine supports it. summary: type: string description: >- A per-result summary, when `content.summary` was requested and the engine supports it. score: type: number description: >- Relevance score. Native on Exa, Tavily, and Valyu, on incomparable scales; rank-derived elsewhere. With `fusion` it is the number of engines that returned the page. score_synthesized: type: boolean description: >- True when `score` was derived by Helve rather than reported by the engine. published_date: type: string description: ISO 8601 date when known. author: type: string raw: nullable: true description: >- The engine's original result object, verbatim. Always present. With `fusion`, `{ providers: { exa: …, parallel: … } }` keyed by every engine that returned the page. required: - id - url - title - snippets - score_synthesized additionalProperties: false warnings: type: array items: type: object properties: code: type: string enum: - param_ignored - param_approximated - results_post_filtered description: >- `param_ignored`: the engine cannot express the parameter, so it was dropped. `param_approximated`: emulated, for example `site:` operators or a capped `max_results`. `results_post_filtered`: Helve removed results to honour a filter the engine lacks, or a fusion member was dropped. param: type: string description: The request field the warning concerns. message: type: string required: - code - message additionalProperties: false description: >- How the request was adjusted for the serving engine. Empty when it was honoured exactly. usage: type: object properties: cost_usd: type: number description: >- What this request debited from your balance: the engine's raw price, or the sum of member prices with `fusion`. credits: type: number required: - cost_usd - credits additionalProperties: false latency_ms: type: number description: >- Wall-clock time Helve spent on the request. With `fusion`, roughly the slowest member. required: - id - provider - results - warnings - usage - latency_ms additionalProperties: false '400': description: Invalid request content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '401': description: Missing or invalid API key content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '402': description: Insufficient credits content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '501': description: Provider not available content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '502': description: Provider error content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false '503': description: Provider not configured content: application/json: schema: type: object properties: error: type: object properties: type: type: string enum: - unauthorized - invalid_request - provider_not_available - provider_not_configured - provider_error - not_found - insufficient_credits description: >- Stable machine-readable category. `invalid_request` carries validation issues in `detail`; `provider_error` carries the provider's own error body. message: type: string description: Human-readable explanation. detail: nullable: true description: >- Validation issues for `invalid_request`; the provider's error body for `provider_error`. required: - type - message additionalProperties: false required: - error additionalProperties: false security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from the dashboard, `sk_live_…`, sent as `Authorization: Bearer sk_live_…`. ````