Skip to content

README.md

Latest commit

 

History

History
227 lines (168 loc) · 6.34 KB

README.md

File metadata and controls

227 lines (168 loc) · 6.34 KB

Valyu JavaScript SDK

npm version License: MIT

Search and research APIs built for AI agents. Access web and proprietary data sources through Search, extract content from URLs, generate grounded answers, and run multi-step research with DeepResearch - all through a single SDK.

Documentation | API Reference | Platform

Installation

npm install valyu-js

Quick Start

import { Valyu } from "valyu-js";

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

const response = await valyu.search("latest advances in transformer architectures", {
  maxNumResults: 5,
  searchType: "all",
});

for (const result of response.results) {
  console.log(result.title, result.url);
}

Get $10 free credits when you sign up at platform.valyu.ai. No credit card required.

APIs

Search

Search across web and proprietary data sources with a single query.

const response = await valyu.search("CRISPR gene therapy clinical trials 2026", {
  searchType: "proprietary",                    // "all", "web", or "proprietary"
  maxNumResults: 10,                            // 1-20 results
  includedSources: ["valyu/valyu-pubmed"],      // filter to specific sources
  startDate: "2026-01-01",                      // date filtering
  endDate: "2026-12-31",
});
All search parameters
Parameter Type Default Description
query string required Search query
searchType string "all" "all", "web", or "proprietary"
maxNumResults number 10 Results to return (1-20)
maxPrice number 30 Max price per thousand queries (CPM)
relevanceThreshold number 0.5 Min relevance score (0-1)
includedSources string[] [] Sources to search
excludeSources string[] [] Sources to exclude
startDate string - Start date (YYYY-MM-DD)
endDate string - End date (YYYY-MM-DD)
countryCode string - Country filter (e.g. "US", "GB")
responseLength string | number - "short", "medium", "large", "max", or character count
category string - Category filter

Contents

Extract clean, structured content from URLs. Supports sync (1-10 URLs) and async (up to 50 URLs) modes.

// Basic extraction
const response = await valyu.contents(["https://arxiv.org/abs/2301.00001"]);

// With AI summarization
const response = await valyu.contents(["https://example.com/article"], {
  summary: true,
  responseLength: "medium",
});

// Structured data extraction with JSON schema
const response = await valyu.contents(["https://en.wikipedia.org/wiki/OpenAI"], {
  summary: {
    type: "object",
    properties: {
      company_name: { type: "string" },
      founded_year: { type: "integer" },
    },
  },
});

Answer

AI-generated answers grounded by Valyu's search. Supports streaming.

const response = await valyu.answer("What are the side effects of metformin?", {
  searchType: "proprietary",
  includedSources: ["valyu/valyu-pubmed"],
});

console.log(response.contents);        // AI-generated answer
console.log(response.search_results);  // Source citations

DeepResearch

Multi-step research agent that produces comprehensive reports with citations.

// Start a research task
const task = await valyu.deepresearch.create({
  query: "Compare CRISPR and base editing approaches for sickle cell disease",
  model: "heavy",
  outputFormats: ["markdown", "pdf"],
});

// Wait for completion with progress
const result = await valyu.deepresearch.wait(task.deepresearch_id, {
  onProgress: (status) => {
    console.log(`Step ${status.progress.current_step}/${status.progress.total_steps}`);
  },
});

console.log(result.output);   // Markdown report
console.log(result.pdf_url);  // PDF download link
All DeepResearch methods
Method Description
create(options) Start a new research task
status(taskId) Get task status
wait(taskId, options?) Poll until completion
stream(taskId, callbacks) Stream real-time updates
list(options) List research tasks
update(taskId, instruction) Add follow-up instruction
cancel(taskId) Cancel a running task
delete(taskId) Delete a task
togglePublic(taskId, isPublic) Toggle public access

Batch

Run multiple DeepResearch tasks in parallel.

const batch = await valyu.batch.create({
  name: "Q1 Analysis",
  mode: "fast",
  outputFormats: ["markdown"],
});

await valyu.batch.addTasks(batch.batch_id, {
  tasks: [
    { query: "Analyze recent SPAC performance" },
    { query: "Review semiconductor supply chain trends" },
  ],
});

const result = await valyu.batch.waitForCompletion(batch.batch_id, {
  onProgress: (b) => console.log(`${b.counts.completed}/${b.counts.total}`),
});

Data Sources

List available data sources programmatically.

const sources = await valyu.datasources.list();
const categories = await valyu.datasources.categories();

Authentication

export VALYU_API_KEY="your-api-key"

Or pass directly:

const valyu = new Valyu("your-api-key");

TypeScript

Full type definitions are included. All request and response types are exported:

import { Valyu, SearchOptions, SearchResponse, SearchResult } from "valyu-js";

Error Handling

const response = await valyu.search("test");

if (!response.success) {
  console.error(response.error);
  console.error(`tx_id: ${response.tx_id}`);
}

Integrations

Valyu works with Vercel AI SDK, LangChain, MCP, and more. See docs.valyu.ai for integration guides.

Links

License

MIT