@youdotcom-oss/api

You.com API client with bundled CLI for AI agents that can use bash commands

Fast, lightweight API client and CLI tools for web search, research, and content extraction. Optimized for AI agents supporting the Agent Skills Spec with built-in support for calling bash commands.

Features

• ⚡ Faster than builtin search APIs - Optimized infrastructure for agent workloads
• 🔬 Research - Comprehensive answers with cited sources and multi-step reasoning
• 🔄 Livecrawl - Search AND extract content in one API call
• ✅ Verifiable references - Every result includes citation URLs
• 📱 Agent skills optimized - JSON output for bash pipelines (jq, grep, awk)
• 🛠️ Dual interface - CLI tools AND programmatic TypeScript API
• 🪶 Lightweight - No heavy dependencies, just Zod for validation

Quick Start

CLI Usage

# Use with bunx (no install needed) - Positional JSON input
bunx @youdotcom-oss/api search '{"query":"AI developments"}' --client ClaudeCode

# Or install globally to use 'ydc' command
bun i -g @youdotcom-oss/api
ydc search '{"query":"AI developments"}' --client ClaudeCode

# Research with cited sources
ydc research '{"input":"What happened in AI this week?","research_effort":"deep"}'

# Extract web content
ydc contents '{"urls":["https://example.com"],"formats":["markdown"]}'

# Pipe JSON via stdin
echo '{"query":"AI"}' | ydc search

# Discover available parameters
ydc search --help
ydc search --schema input | jq '.properties | keys'
ydc search --schema output

Programmatic Usage

import { fetchSearchResults } from '@youdotcom-oss/api';

const getUserAgent = () => 'MyApp/1.0.0 (You.com)';

const results = await fetchSearchResults({
  searchQuery: { query: 'AI developments', livecrawl: 'web' },
  YDC_API_KEY: process.env.YDC_API_KEY,
  getUserAgent,
});

console.log(results.results.web);

Installation

# Bun (recommended for CLI)
bun add @youdotcom-oss/api

# npm
npm install @youdotcom-oss/api

# yarn
yarn add @youdotcom-oss/api

# pnpm
pnpm add @youdotcom-oss/api

Global installation for CLI:

bun i -g @youdotcom-oss/api

Setup

Get API Key:

1. Visit https://you.com/platform/api-keys
2. Create new API key
3. Set environment variable:

export YDC_API_KEY="your-api-key"
export YDC_CLIENT="YourAgentName"  # Optional: default client for tracking

CLI Reference

Unix-style JSON input: This CLI is optimized for AI agents using bash commands. All query parameters are passed as JSON via positional argument or stdin pipe.

Commands

ydc search '{"query":"..."}'
ydc research '{"input":"...","research_effort":"standard"}'
ydc contents '{"urls":["..."]}'

Global Options

• --api-key <key> - You.com API key (overrides YDC_API_KEY)
• --client <name> - Client name for tracking (overrides YDC_CLIENT)
• --schema <input|output> - Output JSON schema and exit
• --dry-run - Show request details without making API call
• --help, -h - Show help (per-command with ydc <cmd> --help)

Schema Discovery

Use --schema and --help to discover what parameters each command accepts:

# Per-command help with parameter table
ydc search --help
ydc research --help

# Get input schema for search command
ydc search --schema input

# Get response schema
ydc search --schema output

# Default: --schema without value shows input schema
ydc search --schema

Search Command

ydc search '{"query":"..."}' [options]

Examples:
  # Basic search
  ydc search '{"query":"machine learning"}' --client ClaudeCode

  # Search with livecrawl (KEY FEATURE)
  ydc search '{
    "query":"documentation",
    "livecrawl":"web",
    "livecrawl_formats":"markdown"
  }' --client ClaudeCode

  # Advanced filters
  ydc search '{
    "query":"AI papers",
    "site":"arxiv.org",
    "fileType":"pdf",
    "freshness":"month",
    "count":10
  }' --client ClaudeCode

  # Parse with jq
  ydc search '{"query":"AI"}' --client ClaudeCode | \
    jq -r '.results.web[] | .title'

  # Extract livecrawl content
  ydc search '{
    "query":"docs",
    "livecrawl":"web",
    "livecrawl_formats":"markdown"
  }' --client ClaudeCode | \
    jq -r '.results.web[0].contents.markdown'

Available search parameters (use --help to see full parameter table):

• query (required) - Search query string
• count - Max results per section (1-100)
• offset - Pagination offset (0-9)
• freshness - day/week/month/year or date range (YYYY-MM-DDtoYYYY-MM-DD)
• country - Country code (e.g., US, GB)
• safesearch - off/moderate/strict
• site - Filter to specific domain
• fileType - Filter by file type
• language - ISO 639-1 language code
• exclude_terms - Exclude terms (pipe-separated)
• exact_terms - Exact match terms (pipe-separated)
• livecrawl - Live-crawl sections: web/news/all
• livecrawl_formats - html/markdown

Research Command

ydc research '{"input":"..."}' [options]

Examples:
  # Standard research (default effort)
  ydc research '{"input":"What is quantum computing?"}' --client ClaudeCode

  # Thorough research (takes longer)
  ydc research '{
    "input":"Latest breakthroughs in AI agents",
    "research_effort":"deep"
  }' --client ClaudeCode

  # Parse answer and sources
  ydc research '{
    "input":"AI trends 2026"
  }' --client ClaudeCode | \
    jq -r '.output.content, "\nSources:", (.output.sources[]? | "- \(.title): \(.url)")'

  # Pipe via stdin
  echo '{"input":"Explain WebAssembly"}' | ydc research

Available research parameters (use --help to see full parameter table):

• input (required) - Research question requiring in-depth investigation
• research_effort - Effort level: lite (fast), standard (default), deep (thorough), exhaustive (most comprehensive)

Contents Command

ydc contents '{"urls":["..."]}' [options]

Examples:
  # Extract markdown
  ydc contents '{
    "urls":["https://example.com"],
    "formats":["markdown"]
  }' --client ClaudeCode

  # Multiple formats
  ydc contents '{
    "urls":["https://example.com"],
    "formats":["markdown","html","metadata"]
  }' --client ClaudeCode

  # Multiple URLs
  ydc contents '{
    "urls":["https://a.com","https://b.com"],
    "formats":["markdown"]
  }' --client ClaudeCode

  # Save to file
  ydc contents '{
    "urls":["https://example.com"],
    "formats":["markdown"]
  }' --client ClaudeCode | \
    jq -r '.[0].markdown' > output.md

  # With timeout
  ydc contents '{
    "urls":["https://example.com"],
    "formats":["markdown","metadata"],
    "crawl_timeout":30
  }' --client ClaudeCode

Available contents parameters (use --help to see full parameter table):

• urls (required) - Array of URLs to extract
• formats - Array of formats: markdown, html, metadata
• crawl_timeout - Timeout in seconds (1-60)

Output Format

Stdout/stderr separation - The CLI uses stream separation to indicate success/failure:

• Success (exit code 0): Direct API response on stdout

  {"results":{"web":[...]},"metadata":{...}}

• Error (exit code 1): Error message + mailto link on stderr

  Error: Missing required input
  mailto:[email protected]?subject=API%20Issue%20CLI...

• Invalid args (exit code 2): Error message on stderr

No wrapper - Success responses contain the direct API response without a wrapper. This makes bash pipelines simpler:

# Direct access to response fields
ydc search '{"query":"AI"}' | jq '.results.web[0].title'

# No need to unwrap .data or .success

Environment Variables

• YDC_API_KEY - You.com API key (required)
• YDC_CLIENT - Default client name for tracking

CLI Exit Codes

• 0 - Success (response on stdout)
• 1 - API error (rate limit, auth, network) - error on stderr
• 2 - Invalid arguments - error on stderr

Programmatic API

All fetch functions accept an optional customHeaders parameter for passing custom HTTP headers (e.g., proxy authentication). Standard headers (X-API-Key, User-Agent) always take precedence.

Search

import { fetchSearchResults, SearchQuerySchema } from '@youdotcom-oss/api';

const getUserAgent = () => 'MyApp/1.0.0 (You.com)';

const response = await fetchSearchResults({
  searchQuery: {
    query: 'AI developments',
    count: 10,
    livecrawl: 'web',
    livecrawl_formats: 'markdown',
  },
  YDC_API_KEY: process.env.YDC_API_KEY,
  getUserAgent,
  customHeaders: { 'X-Custom': 'value' }, // optional
});

// Access results
console.log(response.results.web); // Web results with optional contents
console.log(response.results.news); // News results
console.log(response.metadata); // Query metadata

Research

import { callResearch, ResearchQuerySchema } from '@youdotcom-oss/api';

const response = await callResearch({
  researchQuery: {
    input: 'What happened in AI this week?',
    research_effort: 'deep', // lite | standard | deep | exhaustive
  },
  YDC_API_KEY: process.env.YDC_API_KEY,
  getUserAgent,
});

console.log(response.output.content); // Comprehensive answer with inline citations
console.log(response.output.sources); // Array of sources with URLs, titles, and snippets

Contents

import { fetchContents, ContentsQuerySchema } from '@youdotcom-oss/api';

const response = await fetchContents({
  contentsQuery: {
    urls: ['https://example.com'],
    formats: ['markdown', 'html', 'metadata'],
  },
  YDC_API_KEY: process.env.YDC_API_KEY,
  getUserAgent,
});

console.log(response[0].markdown); // Markdown content
console.log(response[0].html); // HTML content
console.log(response[0].metadata); // Structured metadata

Bash Integration

Error Handling

#!/usr/bin/env bash
set -e

# Capture result, check exit code
if ! result=$(ydc search '{"query":"AI developments"}' --client ClaudeCode); then
  echo "Search failed with code $?"
  exit 1
fi

# Parse success response from stdout
echo "$result" | jq .

Retry on Rate Limit

#!/usr/bin/env bash
for i in {1..3}; do
  if ydc search '{"query":"AI"}' --client ClaudeCode; then
    exit 0
  fi
  [ $i -lt 3 ] && sleep 5
done
echo "Failed after 3 attempts"
exit 1

Parallel Execution

#!/usr/bin/env bash
ydc search '{"query":"AI"}' --client ClaudeCode &
ydc search '{"query":"ML"}' --client ClaudeCode &
ydc search '{"query":"LLM"}' --client ClaudeCode &
wait

Agent Workflow

#!/usr/bin/env bash
set -e

# Search with livecrawl
search=$(ydc search '{
  "query":"AI 2026",
  "count":5,
  "livecrawl":"web",
  "livecrawl_formats":"markdown"
}' --client ClaudeCode)

# Get comprehensive research with citations
answer=$(ydc research '{
  "input":"Summarize AI developments in 2026",
  "research_effort":"deep"
}' --client ClaudeCode)

# Extract top result URL and fetch content
url=$(echo "$search" | jq -r '.results.web[0].url')
ydc contents "{\"urls\":[\"$url\"],\"formats\":[\"markdown\"]}" \
  --client ClaudeCode | jq -r '.[0].markdown' > output.md

Schema-Driven Agent

#!/usr/bin/env bash
set -e

# Discover available search parameters
ydc search --help

# Or get machine-readable schema
schema=$(ydc search --schema input)
echo "$schema" | jq '.properties | keys'

# Build query dynamically
query=$(jq -n '{
  query: "AI developments",
  count: 10,
  livecrawl: "web",
  livecrawl_formats: "markdown"
}')

# Execute search
ydc search "$query" --client ClaudeCode

Agent Skills Integration

This package is designed for agents that support the Agent Skills Spec. The youdotcom-cli skill provides guided workflows for agents to integrate You.com capabilities.

What Agents Get

The youdotcom-cli skill teaches agents:

• Schema Discovery - Use --schema and --help to discover available parameters
• Runtime Setup - Check for Node.js/Bun, install if needed
• API Configuration - Set up API keys and client tracking
• Command Patterns - Positional JSON input with compact output
• Error Handling - Stdout/stderr separation with exit codes
• Advanced Workflows - Livecrawl, parallel execution, rate limiting

Compatible Agents

Works with any bash-capable agent supporting Agent Skills:

• Claude Code - Anthropic's coding tool
• Cursor - AI-powered code editor
• Droid - Factory.ai agent
• Codex - OpenAI's CLI agent
• Roo Code - VS Code extension
• And more...

Installation for Agents

# Add skill to agent's skills directory
npx skills add youdotcom-oss/agent-skills --skill youdotcom-cli

Using the CLI: See the skill's SKILL.md for complete integration workflow.

TypeScript Types

All functions are fully typed with TypeScript. Import types alongside functions:

import type {
  SearchQuery,
  SearchResponse,
  ResearchQuery,
  ResearchResponse,
  ContentsQuery,
  ContentsApiResponse,
} from '@youdotcom-oss/api';

Error Handling

All API functions throw descriptive errors:

try {
  const results = await fetchSearchResults({
    searchQuery: { query: 'test' },
    YDC_API_KEY: process.env.YDC_API_KEY,
    getUserAgent,
  });
} catch (error) {
  if (error.message.includes('Rate limited')) {
    // Handle rate limit
  } else if (error.message.includes('Forbidden')) {
    // Handle auth error
  } else {
    // Handle other errors
  }
}

Development

# Install dependencies
bun install

# Build CLI
bun run build

# Run tests
bun test

# Type check
bun run check:types

# Format code
bun run format

Related Packages

• @youdotcom-oss/mcp - Model Context Protocol server
• @youdotcom-oss/ai-sdk-plugin - Vercel AI SDK integration
• @youdotcom-oss/langchain - LangChain.js integration

Support

• Issues: GitHub Issues
• API Keys: https://you.com/platform/api-keys
• Documentation: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api
• Email: [email protected]

License

MIT © You.com