> ## 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.

# SDKs

> Official TypeScript and Python clients, typed from the same spec the server validates with.

Both clients are thin wrappers over the HTTP API: the same parameters, the same response shapes, nothing renamed. They add authentication, retries on 429, 502, 503, and network failures, typed errors, and a helper that polls transcription jobs to completion.

<CardGroup cols={2}>
  <Card title="TypeScript" icon="js" href="https://www.npmjs.com/package/helve-sdk">
    `npm install helve-sdk`. Zero dependencies. Node 18+, Bun, Deno, and browsers.
  </Card>

  <Card title="Python" icon="python" href="https://pypi.org/project/helve/">
    `pip install helve`. Sync and async clients on `httpx`. Python 3.9+.
  </Card>
</CardGroup>

## TypeScript

```ts theme={null}
import { Helve } from "helve-sdk";

const helve = new Helve({ apiKey: process.env.HELVE_API_KEY });

const { results, provider, usage } = await helve.search({
  query: "latest research on speculative decoding",
  provider: "fusion",
  max_results: 5,
});

const pages = await helve.extract({
  urls: results.map((r) => r.url),
  content: { max_chars: 4000 },
});

const job = await helve.transcriptions.createAndWait({
  audio_url: "https://example.com/standup.mp3",
  diarize: true,
});
if (job.status === "completed") console.log(job.result?.text);
```

Every request and response type is generated from Helve's OpenAPI document, so your editor's hover text is the API reference. `SearchParams`, `SearchResponse`, `ExtractParams`, `Job`, and the rest are exported.

Options: `new Helve({ apiKey, baseUrl, timeoutMs, maxRetries, fetch })`. Every method accepts `{ signal }` for cancellation. `jobs.wait` and `transcriptions.createAndWait` also take `{ intervalMs, timeoutMs }`.

## Python

```python theme={null}
from helve import Helve

helve = Helve()  # reads HELVE_API_KEY

res = helve.search("latest research on speculative decoding", provider="fusion", max_results=5)
print(res["provider"], res["usage"]["cost_usd"])

pages = helve.extract([r["url"] for r in res["results"]], content={"max_chars": 4000})

job = helve.transcriptions.create_and_wait("https://example.com/standup.mp3", diarize=True)
if job["status"] == "completed":
    print(job["result"]["text"])
```

The async client has the same methods:

```python theme={null}
from helve import AsyncHelve

async with AsyncHelve() as helve:
    res = await helve.search("who won the 2026 Abel Prize")
```

Options: `Helve(api_key=None, base_url=..., timeout=60.0, max_retries=2)`. `jobs.wait` and `transcriptions.create_and_wait` take `interval=` and a wait timeout.

## Errors

Both clients raise or throw `HelveError` for any non-2xx response, carrying `status`, a stable `type` matching the [error table](/concepts/errors), the message, and `detail`. A job that ends in `failed` is returned, not thrown: check `job.status` and read `job.error`.

## Other languages

The API is plain JSON over HTTPS with a bearer token, and the [OpenAPI document](https://helve.dev/openapi.json) is complete, so any generator or a few lines of your HTTP client of choice will do. The [quickstart](/quickstart) shows the raw cURL form.