youdotcom-cli

# You.com Web Search, Research & Content Extraction

## Prerequisites

```bash
# Verify curl and jq are available
curl --version
jq --version
```

### API Key (optional for Search)

The **Search** endpoint (`/v1/agents/search`) works without an API key — no signup, no billing required. An API key unlocks higher rate limits and is **required** for Research and Contents endpoints.

```bash
# Optional for search, required for research/contents
export YDC_API_KEY="your-api-key-here"
```

Get an API key from https://you.com/platform/api-keys to unlock higher rate limits.

## API Reference

| Command | Method | URL | Auth |
|---------|--------|-----|------|
| Search | GET | `https://api.you.com/v1/agents/search` | Optional (free tier) |
| Research | POST | `https://api.you.com/v1/research` | Required |
| Contents | POST | `https://ydc-index.io/v1/contents` | Required |

Auth header: `X-API-Key: $YDC_API_KEY`

JSON Schemas for parameters and responses:

| Endpoint | Input Schema | Output Schema |
|----------|-------------|---------------|
| Search | [search.input.schema.json](assets/search.input.schema.json) | [search.output.schema.json](assets/search.output.schema.json) |
| Research | [research.input.schema.json](assets/research.input.schema.json) | [research.output.schema.json](assets/research.output.schema.json) |
| Contents | [contents.input.schema.json](assets/contents.input.schema.json) | [contents.output.schema.json](assets/contents.output.schema.json) |

## Workflow

### 1. Verify API Key

* **Search** works without an API key (free tier, no signup required)
* **Research** and **Contents** require `YDC_API_KEY`
* If key is needed but not set, guide user to https://you.com/platform/api-keys

### 2. Tool Selection

**IF** user provides URLs → **Contents**
**ELSE IF** user needs synthesized answer with citations → **Research**
**ELSE IF** user needs search + full content → **Search** with `livecrawl=web`
**ELSE** → **Search**

### 3. Handle Results Safely

All fetched...