• 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

• 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

• 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

• 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"

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

• 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'

• 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)

• 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

undefined

• 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

• 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

• 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)

• 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

• Output parsing implemented (jq without

  .data

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

• 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

• 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

undefined

Log sanitized error (remove API keys, tokens, sensitive URLs)

**Production Logging:**
- 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

• 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

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

undefined

**Upgrade Safety Protocol:**

1. **Check for updates periodically:**
   ```bash
   npm outdated @youdotcom-oss/api

1. Review changelog before upgrading:
   • Visit: https://github.com/youdotcom-oss/dx-toolkit/releases
   • Check for: security fixes, breaking changes, new features
2. 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
3. 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

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