{"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."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from the dashboard, `sk_live_…`, sent as `Authorization: Bearer sk_live_…`."}},"schemas":{},"parameters":{}},"paths":{"/v1/transcriptions":{"post":{"operationId":"createTranscription","tags":["Transcription"],"summary":"Transcribe a recording","description":"Submits a prerecorded file by URL and returns a job immediately. Helve records the attempt before contacting the provider, retries rate limits, never re-sends an uncertain submission, and fails the job at its deadline rather than leaving it hanging. Poll `GET /v1/jobs/{id}` for the transcript.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"audio_url":"https://example.com/recordings/standup.mp3","provider":"auto","diarize":true,"keyterms":["Helve","Stirrup"]},"schema":{"type":"object","properties":{"audio_url":{"type":"string","format":"uri","description":"HTTPS URL of the recording, fetched by the provider. Signed URLs are fine; it must stay reachable until the provider has read it. No embedded credentials or fragments."},"provider":{"type":"string","enum":["assemblyai","deepgram","elevenlabs","auto"],"description":"Which speech-to-text provider runs the job. `auto` (default) picks the first configured provider. The choice is persisted on the job before execution."},"language":{"type":"string","pattern":"^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$","description":"BCP-47-style language tag such as `en` or `en-US`. Omit to let the provider detect the language."},"diarize":{"type":"boolean","description":"Label speakers in `words` as `speaker_0`, `speaker_1`, … in order of first appearance. Default false."},"keyterms":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Recognition hints: names, jargon, product terms. Supported on AssemblyAI, Deepgram Nova-3, and ElevenLabs Scribe v2; other models ignore them with a warning."},"timestamps":{"type":"string","enum":["word","none"],"description":"`word` (default) returns per-word timings in `result.words`; `none` omits them."},"strict":{"type":"boolean","description":"When true, any option the selected provider or model cannot honour rejects the request instead of producing a warning. Default false."},"provider_options":{"type":"object","properties":{"assemblyai":{"type":"object","additionalProperties":{"nullable":true},"description":"AssemblyAI-native options, for example `{ \"model\": \"best\" }`."},"deepgram":{"type":"object","additionalProperties":{"nullable":true},"description":"Deepgram-native options, for example `{ \"model\": \"nova-3\" }`."},"elevenlabs":{"type":"object","additionalProperties":{"nullable":true},"description":"ElevenLabs-native options, for example `{ \"model_id\": \"scribe_v2\" }`."}},"additionalProperties":false,"description":"Provider-native options, validated by the adapter. Model selection lives here. Transport settings such as URLs, callbacks, and authentication cannot be overridden."}},"required":["audio_url"],"additionalProperties":false}}}},"responses":{"202":{"description":"Transcription accepted","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^job_[0-9a-f-]{36}$","description":"The job id, `job_…`. Poll `GET /v1/jobs/{id}` with it."},"tool":{"type":"string","enum":["transcription"]},"status":{"type":"string","enum":["queued","running","completed","failed"],"description":"`queued` and `running` are in progress; `completed` carries `result`; `failed` carries `error`."},"provider":{"type":"string","enum":["assemblyai","deepgram","elevenlabs"],"description":"The provider selected for this job, resolved from `auto`."},"model":{"type":"string","description":"The provider model the job will run on."},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"param":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"description":"Options the selected provider or model cannot honour. Empty when the request was accepted exactly."},"created_at":{"type":"string","format":"date-time"}},"required":["id","tool","status","provider","model","warnings","created_at"],"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}}}},"404":{"description":"Job not found","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":"Durable execution or provider unavailable","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}}}}}}},"/v1/jobs/{id}":{"get":{"operationId":"getJob","tags":["Transcription"],"summary":"Get a job","description":"One read for the whole lifecycle: state while the job runs, the transcript in `result` once it completes, the reason in `error` once it fails. Jobs are retained for seven days.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^job_[0-9a-f-]{36}$","description":"The job id returned when the recording was submitted."},"required":true,"description":"The job id returned when the recording was submitted.","name":"id","in":"path"}],"responses":{"200":{"description":"Job state, with the transcript once completed or the error once failed","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^job_[0-9a-f-]{36}$"},"tool":{"type":"string","enum":["transcription"]},"status":{"type":"string","enum":["queued","running","completed","failed"],"description":"`queued` and `running` are in progress; `completed` carries `result`; `failed` carries `error`."},"provider":{"type":"string","enum":["assemblyai","deepgram","elevenlabs"]},"model":{"type":"string","nullable":true},"attempt_status":{"type":"string","enum":["queued","submitting","waiting","unknown","completed","failed"],"description":"Where the current provider attempt is: `waiting` means the provider accepted the audio and Helve is polling or awaiting its callback; `unknown` means Helve is reconciling an uncertain submission rather than re-sending it."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","nullable":true,"format":"date-time","description":"Set once the job is `completed` or `failed`."},"result":{"type":"object","nullable":true,"properties":{"text":{"type":"string","description":"The complete transcript with punctuation, as the provider produced it. Empty is valid for silence."},"language":{"type":"string","pattern":"^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$","description":"Detected or requested language tag."},"duration_seconds":{"type":"number","minimum":0,"description":"Recording length when the provider reports it. Transcription is billed on this."},"words":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"start":{"type":"number","minimum":0,"description":"Seconds from the start of the recording."},"end":{"type":"number","minimum":0,"description":"Seconds from the start of the recording."},"speaker_id":{"type":"string","pattern":"^speaker_(0|[1-9]\\d*)$","description":"Present when `diarize` was set. Speaker ids are local to this transcript."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Provider-reported 0–1 confidence. Not comparable across providers."}},"required":["text","start","end"],"additionalProperties":false},"description":"Per-word timings, omitted when `timestamps` is `none`."},"provider":{"type":"string","enum":["assemblyai","deepgram","elevenlabs"]},"model":{"type":"string","nullable":true},"usage":{"type":"object","properties":{"cost_usd":{"type":"number","minimum":0,"description":"What this transcription debited from your balance."},"credits":{"type":"integer","minimum":0}},"required":["cost_usd","credits"],"additionalProperties":false,"description":"Present once the provider reported a duration: the charge for this transcription."}},"required":["text","provider","model"],"additionalProperties":false,"description":"The transcript, present only when `status` is `completed`."},"error":{"type":"object","nullable":true,"properties":{"type":{"type":"string"},"message":{"type":"string"}},"required":["type","message"],"additionalProperties":{"nullable":true},"description":"Why the job failed, present only when `status` is `failed`."}},"required":["id","tool","status","provider","model","attempt_status","created_at","updated_at","finished_at","result","error"],"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}}}},"404":{"description":"Job not found","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":"Durable execution or provider unavailable","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}}}}}}},"/v1/search":{"post":{"operationId":"search","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.","security":[{"bearerAuth":[]}],"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}}}}}}},"/v1/extract":{"post":{"operationId":"extract","tags":["Extract"],"summary":"Extract page content","description":"URLs in, clean content out. Returns the full page as markdown or text, and optionally focused excerpts and a summary when you pass a `query`. URLs the provider cannot fetch are listed in `failed` rather than failing the whole request.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"example":{"urls":["https://arxiv.org/abs/2211.17192"],"query":"how does speculative decoding work","content":{"excerpts":{"max_per_url":3}}},"schema":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"},"minItems":1,"maxItems":20,"description":"The pages to extract, 1–20 absolute URLs. Providers that take one URL per call are fanned out by Helve."},"provider":{"type":"string","enum":["exa","tavily","parallel","serper","firecrawl","linkup","valyu","jina","octen","auto"],"description":"Which provider fetches and cleans the pages. `auto` (default) picks the first configured provider in Helve's priority order. Brave and Perplexity have no extraction product."},"query":{"type":"string","minLength":1,"description":"What you are extracting for. Drives focused excerpts and summaries on providers that support them (Exa, Tavily, Parallel, Firecrawl, Valyu)."},"content":{"type":"object","properties":{"full_text":{"type":"boolean","description":"Return the whole page in `content`. Default true."},"max_chars":{"type":"integer","minimum":100,"maximum":100000,"description":"Cap on `content` length per URL. Native on Exa; Helve truncates for other providers."},"excerpts":{"type":"object","properties":{"max_per_url":{"type":"integer","minimum":1,"maximum":20,"description":"Cap on the number of excerpts per URL."},"max_chars_per_excerpt":{"type":"integer","minimum":1,"description":"Cap on the length of each excerpt, in characters."}},"additionalProperties":false,"description":"Return focused excerpts in `excerpts`, instead of or alongside the full text. Most useful with `query`."},"summary":{"type":"boolean","description":"Return a per-URL summary in `summary`. Native on Exa and Valyu."},"format":{"type":"string","enum":["markdown","text"],"description":"Output format for `content`. Native on Tavily and Serper; most providers return markdown regardless."}},"additionalProperties":false,"description":"What to return for each URL."},"include_links":{"type":"boolean","description":"Return the page's outbound links in `links`. Native on Exa."},"include_images":{"type":"boolean","description":"Return the page's image URLs in `images`. Native on Exa and Tavily."},"max_age_hours":{"type":"integer","minimum":0,"maximum":720,"description":"Accept a cached copy up to this many hours old; 0 forces a live fetch. Native on Exa."},"timeout_ms":{"type":"integer","minimum":1000,"maximum":90000,"description":"Per-page fetch timeout in milliseconds, 1000–90000. Native on Exa and Tavily."},"strict":{"type":"boolean","description":"When true, any parameter the serving provider cannot honour is a 400 instead of a warning. 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."},"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."}},"additionalProperties":false,"description":"Escape hatch for provider-native parameters, keyed by provider id and merged into that provider's request unchanged."}},"required":["urls"],"additionalProperties":false}}}},"responses":{"200":{"description":"Extracted content","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Helve's id for this extraction, `ext_…`."},"provider":{"type":"string","enum":["exa","tavily","parallel","serper","firecrawl","linkup","valyu","jina","octen"],"description":"The provider that served the request, resolved from `auto`."},"results":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"The URL as requested."},"final_url":{"type":"string","description":"The URL after redirects, when the provider reports it."},"title":{"type":"string"},"content":{"type":"string","description":"The full extracted page, in markdown or text per `content.format`."},"excerpts":{"type":"array","items":{"type":"string"},"description":"Focused excerpts, when requested."},"summary":{"type":"string","description":"Per-URL summary, when requested and supported."},"published_date":{"type":"string","description":"ISO 8601 date when known."},"author":{"type":"string"},"links":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"string"}},"raw":{"nullable":true,"description":"The provider's original result object, verbatim. Always present."}},"required":["url"],"additionalProperties":false},"description":"One entry per successfully extracted URL."},"failed":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"error":{"type":"string"}},"required":["url","error"],"additionalProperties":false},"description":"URLs the provider could not fetch, with its reason. Partial success is a 200."},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["param_ignored","param_approximated","results_post_filtered"]},"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 provider. Empty when it was honoured exactly."},"usage":{"type":"object","properties":{"cost_usd":{"type":"number","description":"What this request debited from your balance: the provider's raw price."},"credits":{"type":"number"}},"required":["cost_usd","credits"],"additionalProperties":false},"latency_ms":{"type":"number","description":"Wall-clock time Helve spent on the request."}},"required":["id","provider","results","failed","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}}}},"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}}}}}}}}}