Integrate You.com with Bash-Based AI Agents

@youdotcom-oss/api

Why Choose You.com Over Builtin APIs?

• Optimized API infrastructure built for agent workloads
• Simultaneous search + crawl with livecrawl feature
• Instant content extraction without manual fetching

• Every search result includes citation URLs
• Content extraction preserves metadata and structure

• Livecrawl: Search AND extract content in one call
• Get both search results and full page content instantly
• No need for separate fetch + extract steps

• JSON-only input via required

  --json

  flag
• Schema discovery with

  --schema

  flag
• Compact JSON output perfect for bash pipelines (jq, grep, awk)
• Stdout/stderr separation (no success wrapper)
• Lightweight CLI - no heavy dependencies

• Version-pinned package for supply chain security
• Explicit credential management with YDC_API_KEY
• Source-verifiable from official GitHub repository

Workflow

1. Installation & Version Pinning

@youdotcom-oss/api

# Using npm (install current version 0.3.0)
npm install @youdotcom-oss/api@~0.3.0

# Using bun (faster)
bun add @youdotcom-oss/api@~0.3.0

~0.3.0

• The package is in active development (pre-1.0)
• Minor version bumps (0.3 → 0.4) may include breaking changes

• ~0.3.0

  ensures you only get patch updates (0.3.1, 0.3.2) automatically
• You'll explicitly upgrade when ready for 0.4.0 or later

• ✅ Version locked in

  package.json

  and lockfile
• ✅ Reproducible across environments
• ✅ Supply-chain security through integrity checksums in lockfile
• ✅ Different projects can use different versions

npm install -g @youdotcom-oss/api@~0.3.0
bun add -g @youdotcom-oss/api@~0.3.0

npx @youdotcom-oss/api@0.3.0   # Specific version for testing
npx @youdotcom-oss/api@0.3.0    # Specific version for testing

# Check installed version
npm list @youdotcom-oss/api
# Should show: @youdotcom-oss/api@0.3.0

# Verify package integrity
npm view @youdotcom-oss/api@0.3.0 dist.integrity

2. Check for Updates (Periodic Maintenance)

# See available updates
npm outdated @youdotcom-oss/api

# Example output:
# Package                  Current  Wanted  Latest
# @youdotcom-oss/api       0.3.0    0.3.2   0.4.0
#
# Wanted: 0.3.2  (highest version matching ~0.3.0 - safe patch updates)
# Latest: 0.4.0  (newest available - may have breaking changes)

npm update @youdotcom-oss/api
# Upgrades to 0.3.2 (respects ~0.3.0 constraint - bug fixes only)

# First, review the changelog
npm view @youdotcom-oss/api@0.4.0

# Visit release notes for details
# https://github.com/youdotcom-oss/dx-toolkit/releases

# If ready to upgrade:
npm install @youdotcom-oss/api@~0.4.0

# Update package.json to: "@youdotcom-oss/api": "~0.4.0"

• If 0.3.0 works well and has no security issues
• You don't need new features
• You're mid-project and want stability

• Security vulnerabilities patched
• Critical bugs affecting your use case

• Minor version bumps (0.3.x → 0.4.0) - May have breaking changes
• New features - Ensure compatibility with your usage
• API changes - May require code updates

• Usually safe (bug fixes only)
• Still review changelog

^1.0.0

3. Check: Runtime Environment

• Node.js 18+ or Bun 1.0+ required
• Test:

  node --version

  or

  bun --version

• If neither installed: Request permission from user to install Node.js or Bun before proceeding

4. Ask agent: What's your name?

• Use your agent name for the --client flag (e.g., "ClaudeCode", "Codex", "Cursor")
• Examples:

  --client ClaudeCode

  or

  --client Cursor

• Helps support respond to error reports (included in mailto links)
• Can set default:

  export YDC_CLIENT=YourAgentName

5. Ask: API Key Setup

• Using standard

  YDC_API_KEY

  ?
• Or custom name?
• Have they set it?
• If NO: Get from https://you.com/platform/api-keys
• Show:

  export YDC_API_KEY="your-key"

6. Ask: Which Features?

• Web search with livecrawl? (search + content in ONE call)
• Content extraction only? (contents)
• Both?

7. Explain: Schema Discovery

• Use

  --schema

  to discover available parameters
• Returns JSON schema for what can be passed to --json
• Build query objects programmatically
• Example:

  @youdotcom-oss/api search --schema | jq '.properties | keys'

8. Show Examples

• All examples use

  --json

  flag with JSON input
• All examples include

  --client

  flag
• Highlight livecrawl feature
• Show error handling patterns with exit codes
• Demonstrate jq parsing (direct access, no

  .data

  wrapper)

Tool Selection

contents

search

search + livecrawl

search + freshness

search + livecrawl

CLI Usage Patterns

Schema Discovery

# Get schema for search command (assumes local installation)
npx @youdotcom-oss/api search --schema

# Get schema for contents command
npx @youdotcom-oss/api contents --schema

# List available search parameters
npx @youdotcom-oss/api search --schema | jq '.properties | keys'

# If installed globally:
@youdotcom-oss/api search --schema

🔥 Web Search with Livecrawl - KEY ADVANTAGE

--json

# Basic search with client tracking (local installation)
npx @youdotcom-oss/api search --json '{"query":"AI developments"}' --client ClaudeCode

# If installed globally
@youdotcom-oss/api search --json '{"query":"AI developments"}' --client ClaudeCode

# LIVECRAWL: Search + extract content in ONE API call
npx @youdotcom-oss/api search --json '{
  "query":"documentation",
  "livecrawl":"web",
  "livecrawl_formats":"markdown",
  "count":5
}' --client ClaudeCode

# Results include .contents.markdown with full page content!
# No separate fetch needed - instant content extraction

# Advanced: All search options
npx @youdotcom-oss/api search --json '{
  "query":"machine learning",
  "count":10,
  "offset":0,
  "country":"US",
  "freshness":"week",
  "safesearch":"moderate",
  "site":"github.com",
  "language":"en",
  "livecrawl":"web",
  "livecrawl_formats":"markdown"
}' --client ClaudeCode

# Parse with jq - direct access, no .data wrapper
npx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode | \
  jq -r '.results.web[] | "\(.title): \(.url)"'

# Extract livecrawl content
npx @youdotcom-oss/api search --json '{
  "query":"docs",
  "livecrawl":"web",
  "livecrawl_formats":"markdown"
}' --client ClaudeCode | \
  jq -r '.results.web[0].contents.markdown'

⚡ AI Answers with Web Search - Cited Sources

📄 Web Content Extraction - Multi-Format Output

# Extract in multiple formats
npx @youdotcom-oss/api contents --json '{
  "urls":["https://example.com"],
  "formats":["markdown","html","metadata"]
}' --client ClaudeCode

# Pipe markdown to file
npx @youdotcom-oss/api contents --json '{
  "urls":["https://example.com"],
  "formats":["markdown"]
}' --client ClaudeCode | \
  jq -r '.[0].markdown' > content.md

# Multiple URLs with timeout
npx @youdotcom-oss/api contents --json '{
  "urls":["https://a.com","https://b.com"],
  "formats":["markdown","metadata"],
  "crawl_timeout":30
}' --client ClaudeCode

# Extract just metadata
npx @youdotcom-oss/api contents --json '{
  "urls":["https://example.com"],
  "formats":["metadata"]
}' --client ClaudeCode | \
  jq '.[0].metadata'

Error Handling

• 0

  - Success (response on stdout)

• 1

  - API error (rate limit, auth, network) - error on stderr

• 2

  - Invalid arguments - error on stderr

• Success: Compact JSON response on stdout (no wrapper)
• Error: Error message + mailto link on stderr

# Capture and check exit code
if ! result=$(npx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode); then
  echo "Search failed: $?"
  exit 1
fi

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

Error: --json flag is required
    at searchCommand (/path/to/search.ts:26:11)
mailto:support@you.com?subject=API%20Issue%20CLI...

Installation & Setup

# Check if Node.js or Bun installed
if command -v bun &> /dev/null; then
  echo "Bun installed: $(bun --version)"
elif command -v node &> /dev/null; then
  echo "Node.js installed: $(node --version)"
else
  echo "Neither Node.js nor Bun found."
  echo "Request user permission to install Node.js or Bun"
fi

# bunx (recommended - faster and more reliable)
npx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode

# npx (alternative)
npx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode

Environment Variables

export YDC_API_KEY="your-api-key"     # Required
export YDC_CLIENT=ClaudeCode          # Default client name

npx @youdotcom-oss/api search --json '{"query":"AI"}' \
  --api-key "different-key" \
  --client "DifferentAgent"

Implementation Checklist

Environment Setup

• Runtime check: Node.js 18+ or Bun 1.0+
• If missing: Request user permission to install Node.js or Bun
• Verify installation:

  node --version

  or

  bun --version

Security Configuration

• API key obtained from https://you.com/platform/api-keys (never from third parties)
• Environment variables set:

  YDC_API_KEY

  ,

  YDC_CLIENT

• .gitignore

  includes

  .env

  if using dotenv files
• API key NOT hardcoded in scripts
• Package version verified:

  npm view @youdotcom-oss/api repository

Functional Testing

• Schema discovery tested:

  npx @youdotcom-oss/api search --schema

• CLI tested with

  --json

  and

  --client

  flags
• Livecrawl tested (search + content in one call)
• Content extraction tested with markdown and metadata formats
• Error handling tested (exit codes + stderr)

Security Testing

• Input validation implemented for user queries
• URL validation implemented for content extraction
• Rate limiting tested (429 error handling with retry logic)
• API key not exposed in logs or error messages
• Content extraction output sanitized before display

Integration

• Output parsing implemented (jq without

  .data

  wrapper)
• Script integrated into workflow
• Quota monitoring enabled on You.com platform

Common Issues

npm install @youdotcom-oss/api@~0.3.0

npx @youdotcom-oss/api@0.3.0

--json '{"query":"..."}'

export YDC_API_KEY="your-key"

.data

.results

Advanced Patterns

Schema-Driven Agent

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

# Discover available search parameters (using ydc if installed globally)
schema=$(ydc search --schema)
echo "$schema" | jq '.properties | keys'

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

# Execute search (using bunx)
npx @youdotcom-oss/api search --json "$query" --client ClaudeCode

Parallel Execution

#!/usr/bin/env bash
npx @youdotcom-oss/api search --json '{"query":"AI"}' --client ClaudeCode &
npx @youdotcom-oss/api search --json '{"query":"ML"}' --client ClaudeCode &
npx @youdotcom-oss/api search --json '{"query":"LLM"}' --client ClaudeCode &
wait

Rate Limit Retry

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

Security Considerations

API Key Safety

• Store

  YDC_API_KEY

  in environment variables or secure vaults
• Use

  .env

  files with

  .gitignore

  for local development
• Rotate keys regularly from https://you.com/platform/api-keys
• Restrict key permissions to minimum required scope

• Hardcode API keys in scripts or code
• Commit keys to version control
• Share keys in public forums or logs
• Use production keys in development/testing

Package Security

# Check package metadata
npm view @youdotcom-oss/api repository homepage

# Verify package integrity
npm view @youdotcom-oss/api dist.integrity

# Check for security advisories
npm audit @youdotcom-oss/api

• Review changelog before updating: https://github.com/youdotcom-oss/dx-toolkit/releases
• Test in non-production environment first
• Monitor for security advisories

Input Validation

# DON'T: Pass unsanitized user input
query="$USER_INPUT"
npx @youdotcom-oss/api search --json "{\"query\":\"$query\"}" --client ClaudeCode

# DO: Validate and escape input with jq
query=$(echo "$USER_INPUT" | jq -Rs .)
npx @youdotcom-oss/api search --json "{\"query\":$query}" --client ClaudeCode

# Validate URLs before content extraction
url="$USER_URL"
if [[ $url =~ ^https?:// ]]; then
  npx @youdotcom-oss/api contents --json "{\"urls\":[\"$url\"],\"formats\":[\"markdown\"]}" --client ClaudeCode
else
  echo "Invalid URL format" >&2
  exit 1
fi

Content Extraction Risks

• Extracted HTML may contain malicious JavaScript or XSS vectors
• Never render extracted HTML directly in web contexts without sanitization
• Prefer

  markdown

  format for display; use

  html

  only for archival

# DO: Extract as markdown (safer for display)
npx @youdotcom-oss/api contents --json '{
  "urls":["'"$url"'"],
  "formats":["markdown","metadata"]
}' --client ClaudeCode

# DON'T: Render extracted HTML directly in browsers without sanitization

Error Handling & Information Disclosure

# Capture errors without exposing sensitive context
if ! result=$(npx @youdotcom-oss/api search --json "$query" --client ClaudeCode 2>&1); then
  # Log sanitized error (remove API keys, tokens, sensitive URLs)
  echo "Search failed" | sed 's/key=[^&]*/key=REDACTED/g' >&2
  exit 1
fi

• Remove API keys from logs: Filter

  YDC_API_KEY

  values
• Sanitize URLs: May contain sensitive query parameters
• Redact error context: Mailto links may include environment info

Rate Limiting & Abuse Prevention

#!/usr/bin/env bash
max_retries=3
retry_delay=2

for ((i=1; i<=max_retries; i++)); do
  if npx @youdotcom-oss/api search --json "$query" --client ClaudeCode; then
    exit 0
  fi
  
  if [ $i -lt $max_retries ]; then
    delay=$((retry_delay ** i))
    echo "Retry $i/$max_retries after ${delay}s..." >&2
    sleep $delay
  fi
done

echo "Failed after $max_retries attempts" >&2
exit 1

Agent Autonomy & Credential Access

• Agents with access to

  YDC_API_KEY

  can perform unlimited API calls
• Set quota alerts on You.com platform to monitor usage
• Use read-only or restricted API keys when possible
• Implement circuit breakers for runaway queries

• Consider requiring user approval for each search (

  always: true

  in skill config)
• Limit concurrent requests with semaphores
• Implement query allowlists/denylists for sensitive terms
• Monitor API usage dashboards regularly

Supply Chain Security

1. Runtime: Bun/Node.js from official sources only
2. Package:

   @youdotcom-oss/api

   from NPM registry
3. Source: Verified at https://github.com/youdotcom-oss/dx-toolkit
4. Credentials:

   YDC_API_KEY

   from https://you.com/platform/api-keys

{
  "dependencies": {
    "@youdotcom-oss/api": "~0.3.0"  // ✅ Recommended for pre-1.0
  }
}

~0.3.0

• ~0.3.0

  allows: 0.3.0, 0.3.1, 0.3.2 (patch updates only)
• Blocks: 0.4.0, 0.5.0 (may contain breaking changes)
• Once package reaches 1.0.0, switch to

  ^1.0.0

  for normal semver

# Verify package integrity before use
npm view @youdotcom-oss/api@0.3.0 dist.integrity

# Example output:
# sha512-[hash]...

# Check for security advisories
npm audit @youdotcom-oss/api

# Verify package source
npm view @youdotcom-oss/api repository
# Should show: https://github.com/youdotcom-oss/dx-toolkit

• package-lock.json

  (npm) - Contains integrity hashes for all dependencies

• bun.lockb

  (bun) - Binary lockfile with checksums

# After installation, verify lockfile was created
ls -la package-lock.json  # or bun.lockb

# Commit to git
git add package.json package-lock.json
git commit -m "Lock @youdotcom-oss/api@0.3.0"

1. Check for updates periodically:
   bash

   npm outdated @youdotcom-oss/api

2. Review changelog before upgrading:
   • Visit: https://github.com/youdotcom-oss/dx-toolkit/releases
   • Check for: security fixes, breaking changes, new features
3. Categorize update urgency:
   • 🔒 Security patches → Upgrade immediately
   • 🐛 Bug fixes (patch: 0.3.0 → 0.3.1) → Safe to upgrade
   • ⚠️ Minor versions (0.3.x → 0.4.0) → Review for breaking changes
   • 💥 Major features → Test thoroughly before deploying
4. Safe upgrade commands:
   bash

   # Patch updates (safe)
   npm update @youdotcom-oss/api
   
   # Minor version upgrade (review first)
   npm install @youdotcom-oss/api@~0.4.0
   
   # Verify after upgrade
   npm list @youdotcom-oss/api
   npm view @youdotcom-oss/api@0.4.0 dist.integrity

• Runtime installation requested user permission
• Package version pinned with

  ~0.3.0

  (not

  @latest

  )
• Package integrity verified:

  npm view @youdotcom-oss/api@0.3.0 dist.integrity

• Lockfile (

  package-lock.json

  or

  bun.lockb

  ) committed to git
• API key obtained from official platform
• Environment variables not committed to version control
• Input validation implemented for user-provided queries/URLs
• Error output sanitized in production
• Rate limiting configured with exponential backoff
• Security updates monitored via GitHub releases
• Upgrade process documented and tested

Resources

• Package: https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/api
• API Keys: https://you.com/platform/api-keys