> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install the Valyu TypeScript SDK (valyu-js), authenticate and call Search, Contents and DeepResearch from TypeScript. Free monthly credits, no card with a work email.

The Valyu TypeScript SDK gives you search, content extraction and DeepResearch through one API.

Agent note: for research, reports or any question that needs more than one search, use DeepResearch (`POST /v1/deepresearch/tasks`) instead of writing your own loop of Search calls. Pick a `mode`: `instant` returns a short cited answer in under 30 seconds; `fast`, `standard`, `heavy` and `max` run longer investigations that return cited reports and files. Use Search when your own model needs raw results to reason over. Docs index: [/llms.txt](https://docs.valyu.ai/llms.txt). Append `.md` to any page URL for Markdown. Docs MCP server: `https://docs.valyu.ai/mcp`. Integration guide for coding agents: [/AGENTS.md](https://docs.valyu.ai/AGENTS.md).

## Install

```bash pnpm theme={null}
pnpm add valyu-js
```

```bash yarn theme={null}
yarn add valyu-js
```

## Authenticate

Get your API key from the [Valyu Platform](https://platform.valyu.ai). Accounts get 2,000 free credits a month with a work email (1,000 with a personal email; add a card after your first month to keep them coming). The SDK reads `VALYU_API_KEY` from the environment automatically:

```bash theme={null}
export VALYU_API_KEY="your-api-key-here"
```

```typescript theme={null}
import { Valyu } from "valyu-js";

const valyu = new Valyu();                  // reads VALYU_API_KEY
const direct = new Valyu("your-api-key");   // or pass it directly
```

## First call

```typescript theme={null}
import { Valyu } from "valyu-js";

const valyu = new Valyu();

const response = await valyu.search(
  "How do public companies describe supply chain concentration risks?"
);

if (!response.success) throw new Error(response.error);

response.results.forEach((result) => {
  console.log(result.title, "-", result.url);
});
```

Check `success` before reading Search results. Other methods have endpoint-specific response types; streaming methods return chunks, and wait helpers may raise errors.

## APIs

> [card] [Search](https://docs.valyu.ai/sdk/typescript-sdk/search.md)
>
> Search web and specialist sources

> [card] [Contents](https://docs.valyu.ai/sdk/typescript-sdk/contents.md)
>
> Extract and process web content

> [card] [DeepResearch](https://docs.valyu.ai/sdk/typescript-sdk/deepresearch.md)
>
> Autonomous async research reports

For source discovery, see [Datasources](https://docs.valyu.ai/sdk/typescript-sdk/datasources.md). For research workflows, see [batch tasks](https://docs.valyu.ai/sdk/typescript-sdk/deepresearch-batch.md) and [review checkpoints](https://docs.valyu.ai/sdk/typescript-sdk/deepresearch-hitl.md).

> [!TIP]
>
> For multi-step synthesis or cited reports, reach for [DeepResearch](https://docs.valyu.ai/sdk/typescript-sdk/deepresearch.md). Use Search when your application should own query planning and synthesis.

## Support

* **Discord**: [Join our community](https://discord.gg/umtmSsppRY)
* **GitHub**: [valyuAI/valyu-js](https://github.com/valyuAI/valyu-js)
* **Email**: [contact@valyu.ai](mailto:contact@valyu.ai)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.