# Header format
x-api-key: your-api-key-here

{
  "success": true,
  "tx_id": "string",
  "query": "string",
  "results": [
    {
      "id": "string",
      "title": "string",
      "url": "string",
      "content": "string",
      "source": "string",
      "length": 12345,
      "image_url": "string",
      "publication_date": "string",
      "doi": "string",
      "citation": "string",
      "citation_count": 42,
      "authors": ["string"],
      "references": "string",
      "price": 0.001,
      "data_type": "unstructured",
      "source_type": "general"
    }
  ],
  "results_by_source": {
    "web": 5,
    "proprietary": 3
  },
  "total_deduction_pcm": 1.5,
  "total_deduction_dollars": 0.0015,
  "total_characters": 25000
}

{
  "success": true,
  "tx_id": "string",
  "original_query": "string",
  "contents": "string or object",
  "data_type": "unstructured",
  "search_results": [
    {
      "title": "string",
      "url": "string",
      "content": "string",
      "source_type": "string",
      "publication_date": "string",
      "relevance_score": 0.95
    }
  ],
  "search_metadata": {
    "tx_id": "string",
    "result_count": 10,
    "total_characters": 50000
  },
  "ai_usage": {
    "input_tokens": 1000,
    "output_tokens": 500
  },
  "cost": {
    "search_dollars": 0.001,
    "ai_dollars": 0.002,
    "total_dollars": 0.003
  }
}

{
  "success": true,
  "tx_id": "string",
  "results": [
    {
      "title": "string",
      "url": "string",
      "content": "markdown string or JSON object",
      "description": "string",
      "price": 0.001,
      "length": 25000,
      "data_type": "unstructured",
      "image_url": {
        "image1": "url",
        "image2": "url"
      },
      "screenshot_url": "string",
      "summary_success": true
    }
  ],
  "urls_requested": 5,
  "urls_processed": 5,
  "urls_failed": 0,
  "total_cost_dollars": 0.005,
  "total_characters": 125000
}

pip install valyu

from valyu import ValyuClient

client = ValyuClient(api_key="your-api-key")

# Search
results = client.search(
    query="AI agents",
    max_num_results=10,
    search_type="web"
)

# Answer
answer = client.answer(
    query="What are AI agents?",
    streaming=False
)

# Contents
contents = client.contents(
    urls=["https://example.com"],
    summary="Summarize key points"
)

npm install valyu-js

import { ValyuClient } from 'valyu-js';

const client = new ValyuClient({ apiKey: 'your-api-key' });

// Search
const results = await client.search({
  query: 'AI agents',
  max_num_results: 10,
  search_type: 'web'
});

// Answer
const answer = await client.answer({
  query: 'What are AI agents?',
  streaming: false
});

// Contents
const contents = await client.contents({
  urls: ['https://example.com'],
  summary: 'Summarize key points'
});

results = client.search(
    query="latest AI developments 2026",
    search_type="news",
    start_date="2026-01-01",
    max_num_results=20
)

answer = client.answer(
    query="How do neural networks work?",
    system_instructions="Explain in simple terms for beginners",
    included_sources=["wikipedia.org", "arxiv.org"]
)

contents = client.contents(
    urls=["https://docs.example.com"],
    summary={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "key_features": {"type": "array", "items": {"type": "string"}},
            "pricing": {"type": "string"}
        }
    }
)

results = client.search(
    query="quantum computing applications",
    search_type="all",
    response_length="large",
    relevance_threshold=0.8
)

# Results include citations, DOIs, authors for academic sources

# Extract specific data using JSON schema
answer = client.answer(
    query="https://example.com/product",
    structured_output={
        "type": "object",
        "properties": {
            "product_name": {"type": "string"},
            "price": {"type": "number"},
            "features": {"type": "array", "items": {"type": "string"}},
            "rating": {"type": "number"}
        },
        "required": ["product_name", "price"]
    }
)

# Include specific domains
results = client.search(
    query="AI safety research",
    included_sources=["arxiv.org", "openai.com", "anthropic.com"]
)

# Exclude domains
results = client.search(
    query="AI news",
    excluded_sources=["reddit.com", "twitter.com"]
)

# Set maximum spending per request
results = client.search(
    query="comprehensive AI report",
    max_price=0.10,  # Max $0.10 per request
    response_length="large"
)

# cURL Example - Search
curl -X POST https://api.valyu.ai/v1/search \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI agents",
    "max_num_results": 10,
    "search_type": "web"
  }'

# cURL Example - Answer
curl -X POST https://api.valyu.ai/v1/answer \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are transformers in AI?",
    "streaming": false
  }'

# cURL Example - Contents
curl -X POST https://api.valyu.ai/v1/contents \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com"],
    "response_length": "medium",
    "summary": "Extract key information"
  }'

cd ~/.claude/skills/valyu/cli
./install.sh

# Configure API key
echo "VALYU_API_KEY=your-key" > ~/.valyu/.env

# Search
valyu search "AI agents" --num 10 --type web

# Answer
valyu answer "What are transformers?" --instructions "Technical explanation"

# Contents
valyu contents https://example.com --summary "Extract key points"

# Recursive Research (1-10 turns)
valyu research "quantum computing" --turns 5 --threshold 0.85

Turn 1: "quantum computing applications"
  → Confidence: 65%
  → Next: "What are practical quantum algorithms?"

Turn 2: "What are practical quantum algorithms?"
  → Confidence: 78%
  → Next: "How do quantum error correction codes work?"

Turn 3: "How do quantum error correction codes work?"
  → Confidence: 91%
  → STOP (>= 85% threshold)

Final Synthesis: Comprehensive answer from 3 turns

valyu research "How does RAG work with vector databases?" \
  --turns 5 \
  --threshold 0.85 \
  --strategy depth \
  --output ./rag-research

# Output:
# ./rag-research/
# ├── turn-1.md       - Initial findings
# ├── turn-2.md       - Refined query results
# ├── turn-3.md       - Continued refinement
# ├── turn-4.md       - Deep dive
# ├── turn-5.md       - Final iteration
# ├── REPORT.md       - Complete synthesis
# └── results.json    - Full data

# Lower cost (fewer results, fast mode)
valyu search "topic" --num 5 --fast

# Higher quality (more turns, deeper research)
valyu research "topic" --turns 10 --strategy depth

// Use CLI from agent code
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

// Run research
const { stdout } = await execAsync(
  'valyu research "topic" --turns 5 --output ./research'
);

// Parse results
const results = JSON.parse(
  await fs.readFile('./research/results.json', 'utf-8')
);

#!/bin/bash
# Automated research pipeline

topics=("AI safety" "quantum computing" "neural networks")

for topic in "${topics[@]}"; do
  echo "Researching: $topic"
  valyu research "$topic" \
    --turns 5 \
    --strategy balanced \
    --output "research/$(echo $topic | tr ' ' '-')"
done

# Combine reports
cat research/*/REPORT.md > COMBINED_RESEARCH.md

# valyu.flow.yaml (planned)
name: valyu-research
type: lev_plugin
cdo_properties:
  - streaming:
      target_confidence: 85-95
      max_iterations: 10
commands:
  research:
    handler: recursive_research
    params:
      query: string
      turns: number
      strategy: breadth|depth|balanced

# 1. Quick lookup
brave-search "keyword" --num 5

# 2. If insufficient, escalate to Valyu
valyu research "keyword context" --turns 5 --threshold 0.85

# 3. Or orchestrate through lev-research
lev-research "keyword" --template=technology_assessment