Valyu Search

Valyu Complete API Tool

Comprehensive CLI tool for all Valyu APIs: Search, Answer, Contents, and DeepResearch.

Installation

Requirements:

1. Node.js 18+ (uses built-in fetch)
2. Set environment variable: export VALYU_API_KEY=your-api-key
3. Scripts are executable (already set in packaged skill)

Commands Overview

1. SEARCH - Multi-domain search

scripts/valyu search <type> <query> [maxResults]

2. ANSWER - AI-powered answers

scripts/valyu answer <query> [--fast] [--structured <schema>]

3. CONTENTS - Extract content from URLs

scripts/valyu contents <url> [--summary [instructions]] [--structured <schema>]

4. DEEPRESEARCH - Async research reports

scripts/valyu deepresearch create <query> [--model <fast|lite|heavy>] [--pdf]
scripts/valyu deepresearch status <task-id>

1. SEARCH API

Search Types

Usage Examples

# Web search
scripts/valyu search web "AI developments 2025" 10

# Academic papers
scripts/valyu search paper "transformer architectures" 15

# Financial data
scripts/valyu search finance "Apple earnings Q4 2024" 8

# Biomedical research
scripts/valyu search bio "cancer immunotherapy clinical trials"

Output Format

{
  "success": true,
  "type": "search",
  "searchType": "web",
  "query": "AI news",
  "resultCount": 10,
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com",
      "content": "Full content...",
      "source": "web",
      "relevance_score": 0.95
    }
  ],
  "cost": 0.025
}

2. ANSWER API

AI-powered answers with real-time search integration.

Basic Usage

# Simple answer
scripts/valyu answer "What is quantum computing?"

# Fast mode (quicker, less comprehensive)
scripts/valyu answer "Latest AI news" --fast

# With structured output
scripts/valyu answer "Top tech companies 2024" --structured '{
  "type": "object",
  "properties": {
    "companies": {
      "type": "array",
      "items": {"type": "string"}
    },
    "market_summary": {"type": "string"}
  }
}'

Features

• Fast Mode: Lower latency, finance and web sources prioritized
• Structured Output: Define JSON schema for consistent responses
• Source Citations: Returns sources used in the answer
• Search Integration: Automatically searches relevant sources

Output Format

{
  "success": true,
  "type": "answer",
  "query": "What is quantum computing?",
  "answer": "Quantum computing is...",
  "data_type": "unstructured",
  "sources": [
    {
      "title": "Source Title",
      "url": "https://example.com"
    }
  ],
  "cost": 0.032
}

3. CONTENTS API

Extract clean, structured content from web pages.

Basic Usage

# Extract raw content
scripts/valyu contents "https://techcrunch.com/article"

# Extract with AI summary
scripts/valyu contents "https://example.com" --summary

# Extract with custom instructions
scripts/valyu contents "https://example.com" --summary "Summarize key findings in 2 paragraphs"

# Extract structured data
scripts/valyu contents "https://product-page.com" --structured '{
  "type": "object",
  "properties": {
    "product_name": {"type": "string"},
    "price": {"type": "number"},
    "features": {
      "type": "array",
      "items": {"type": "string"}
    }
  },
  "required": ["product_name", "price"]
}'

Features

• Batch Processing: Process multiple URLs (up to 10)
• AI-Powered Summarization: Generate summaries with custom instructions
• Structured Extraction: Extract specific data points using JSON schema
• Response Length Control: short (25k), medium (50k), large (100k), max
• Extract Effort: normal, high, auto

Response Length Options

Output Format

{
  "success": true,
  "type": "contents",
  "urls_requested": 1,
  "urls_processed": 1,
  "urls_failed": 0,
  "results": [
    {
      "title": "Article Title",
      "url": "https://example.com",
      "content": "Extracted content...",
      "data_type": "unstructured",
      "summary_success": true,
      "length": 12840
    }
  ],
  "total_cost": 0.001
}

4. DEEPRESEARCH API

Asynchronous deep research with comprehensive reports.

Research Modes

Create Research Task

# Basic research (lite mode, markdown)
scripts/valyu deepresearch create "AI market trends 2024"

# Heavy mode with PDF output
scripts/valyu deepresearch create "Climate change mitigation strategies" --model heavy --pdf

# Fast mode for quick lookup
scripts/valyu deepresearch create "Current Bitcoin price trends" --model fast

Check Task Status

scripts/valyu deepresearch status f992a8ab-4c91-4322-905f-190107bd5a5b

Output Formats

• Markdown: Default, clean formatted report
• PDF: Add --pdf flag for downloadable PDF
• JSON Schema: Custom structured output (advanced)

Task Lifecycle

queued → running → completed/failed

Statuses:

• queued: Waiting to start
• running: Actively researching
• completed: Research finished
• failed: Error occurred
• cancelled: User cancelled

Create Response

{
  "success": true,
  "type": "deepresearch_create",
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "queued",
  "query": "AI market trends 2024",
  "model": "lite",
  "created_at": 1759617800000
}

Status Response

{
  "success": true,
  "type": "deepresearch_status",
  "deepresearch_id": "f992a8ab-4c91-4322-905f-190107bd5a5b",
  "status": "completed",
  "query": "AI market trends 2024",
  "output": "# AI Market Trends 2024\n\n## Overview...",
  "pdf_url": "https://storage.valyu.ai/reports/...",
  "sources": [
    {
      "title": "Market Analysis 2024",
      "url": "https://example.com",
      "snippet": "Key findings...",
      "source": "web",
      "word_count": 2500
    }
  ],
  "progress": {
    "current_step": 5,
    "total_steps": 5
  },
  "usage": {
    "search_cost": 0.0075,
    "ai_cost": 0.15,
    "total_cost": 0.1575
  },
  "completed_at": 1759617836483
}

Processing Results

With jq

# Get search result titles
scripts/valyu search web "AI" 5 | jq '.results[].title'

# Get answer text
scripts/valyu answer "What is AI?" | jq -r '.answer'

# Get extracted content
scripts/valyu contents "https://example.com" | jq -r '.results[].content'

# Get research output
scripts/valyu deepresearch status <task-id> | jq -r '.output'

# Check if completed
result=$(scripts/valyu deepresearch status <task-id>)
if echo "$result" | jq -e '.status == "completed"' > /dev/null; then
  echo "Research complete!"
fi

Error Handling

All commands return JSON with success field:

{
  "success": false,
  "error": "Error message"
}

Exit codes:

• 0 - Success
• 1 - Error (check JSON for details)

Use Cases

Research Assistant

# Deep research with PDF
scripts/valyu deepresearch create "Blockchain in healthcare" --model heavy --pdf

News Monitoring

# Latest news
scripts/valyu search news "AI regulation EU" 20

Content Aggregation

# Extract and summarize
scripts/valyu contents "https://blog.com/post" --summary "Key takeaways in bullet points"

Quick Q&A

# Fast answer
scripts/valyu answer "Who won the 2024 election?" --fast

Academic Research

# Search papers
scripts/valyu search paper "CRISPR gene editing 2024" 15

Financial Analysis

# Get financial data
scripts/valyu search finance "Tesla stock performance 2024" 10

Requirements

• Node.js 18+ - For built-in fetch API
• VALYU_API_KEY - Environment variable
• No npm packages - Direct API calls only

Get API key: https://platform.valyu.ai ($10 free credits)

API Endpoints Used

• /v1/search - Search API
• /v1/answer - Answer API
• /v1/contents - Contents API
• /v1/deepresearch/tasks - DeepResearch API
• /v1/deepresearch/tasks/{id}/status - Task status

Architecture

scripts/
├── valyu          # Bash wrapper
└── valyu.mjs      # Node.js CLI (all APIs)

Direct API calls using Node.js built-in fetch(), zero external dependencies.