valyu-best-practices

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: valyu-best-practices
description: Complete Valyu API toolkit for AI agents. Use this skill when asked to perform real-time search across web, academic, medical, transportation, financial sources, content extraction from URLs, AI-powered answers with citations, or comprehensive deep research reports.
license: MIT
compatibility: Requires network access and valid Valyu API key
metadata:
  author: valyu
  version: "1.0"
---

# Valyu Best Practices

This skill provides instructions for using the Valyu API to perform search, content extraction, AI-powered answers, and deep research tasks.

## Quick Reference: Choosing the Right API

Use this decision tree to select the appropriate Valyu API:

```
What do you need?

├─ Find information across multiple sources
│  └─ Use Search API
│
├─ Extract content from specific URLs
│  └─ Use Contents API
│
├─ Get an AI-synthesized answer with citations
│  └─ Use Answer API
│
├─ Generate a comprehensive research report
│  └─ Use DeepResearch API
│
└─ Discover available data sources
   └─ Use Datasources API
```

---

## ⚠️ MANDATORY: Use Official Valyu SDK Libraries

**CRITICAL: When writing code that uses the Valyu API, you MUST use the official SDK libraries. NEVER make raw HTTP/fetch calls to the Valyu API endpoints.**

### JavaScript/TypeScript: `valyu-js`

```bash
npm install valyu-js
# or
pnpm add valyu-js
```

```typescript
import { Valyu } from 'valyu-js';

const valyu = new Valyu(process.env.VALYU_API_KEY);

// Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deepResearch
```

### Python: `valyu`

```bash
pip install valyu
# or
uv add valyu
```

```python
from valyu import Valyu

valyu = Valyu(api_key=os.environ.get("VALYU_API_KEY"))

# Now use valyu.search(), valyu.contents(), valyu.answer(), valyu.deep_research
```

### Why SDK Over Raw API Calls?

1. **Type safety** - Full TypeScript/Python type hints for all parameters and responses
2. **Automatic retries** - Built-in retry logic for transient failures
3. **Streaming support** - Proper async iterator support for streaming responses
4. **Error handling** - Structured error types with helpful messages
5. **Future compatibility** - SDK updates handle API changes automatically

### ❌ NEVER Do This

```typescript
// DON'T make raw fetch calls
const response = await fetch('https://api.valyu.ai/v1/search', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: '...' })
});
```

### ✅ Always Do This

```typescript
// DO use the SDK
import { Valyu } from 'valyu-js';

const valyu = new Valyu(process.env.VALYU_API_KEY);
const response = await valyu.search({ query: '...' });
```

---

## 1. Search API

**Purpose:** Find information across web, academic, medical, transportation, financial, news, and proprietary sources.

### When to Use

- Finding recent information on any topic
- Academic research (arXiv, PubMed, bioRxiv, medRxiv)
- Financial data (SEC filings, earnings reports, stock data)
- News monitoring and current events
- Healthcare data (clinical trials, drug labels)
- Prediction markets (Polymarket, Kalshi)
- Transportation (UK National Rail, Global Shipping)

### Basic Usage

```typescript
const response = await valyu.search({
  query: "transformer architecture attention mechanism 2024",
  searchType: "all",
  maxNumResults: 10
});
```

### Search Types

| Type | Use For |
|------|---------|
| `all` | Everything - web, academic, financial, proprietary |
| `web` | General internet content only |
| `proprietary` | Licensed academic papers and research |
| `news` | News articles and current events |

### Key Parameters

| Parameter (TS/JS) | Parameter (Python) | Purpose | Example |
|-------------------|-------------------|---------|---------|
| `query` | `query` | Search query (under 400 chars) | `"CRISPR gene editing 2024"` |
| `searchType` | `search_type` | Source scope | `"all"`, `"web"`, `"proprietary"`, `"news"` |
| `maxNumResults`