youdotcom-api

What this skill does

# Integrate You.com APIs Directly

Build applications that call You.com APIs using standard HTTP clients — no SDK required. The APIs use simple REST endpoints with optional API key authentication — the Search API allows 100 free searches per day without an API key.

You.com provides three APIs that serve different needs:

- **Research API** — Ask a complex question, get a synthesized Markdown answer with inline citations. The API autonomously runs multiple searches, reads pages, cross-references sources, and reasons over the results. One call replaces an entire RAG pipeline.
- **Search API** — Get raw web and news results for a query (100 free searches/day without an API key). You control what happens with the results — feed them into your own LLM, build a custom UI, or process them programmatically.
- **Contents API** — Extract full page content (HTML, Markdown, metadata) from specific URLs. Useful for deep-reading pages found via Search or for crawling known URLs.

## Choose Your Path

**Path A: Research API** — One call to get a cited, synthesized answer to any question
**Path B: Search + Contents** — Raw building blocks for custom search pipelines and data extraction

## Decision Point

**Ask: Do you need a ready-to-use answer with citations, or raw search results you'll process yourself?**

- **Synthesized answer** → Path A (recommended for most use cases, and easier to use)
- **Raw results / custom processing** → Path B

**Also ask:**
1. What language are you using?
2. Where should the code be saved?
3. What are you building? (See [Use Cases](#use-cases) below)
4. What testing framework do you use?

---

## API Reference

The Search API allows **100 free searches per day** without an API key. After the free tier is exhausted, or for Research and Contents APIs, authenticate with the `X-API-Key` header using a You.com API key. Get one for free at https://you.com/platform.

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

### Research API

**Base URL:** `https://api.you.com`
**Endpoint:** `POST /v1/research`

Returns comprehensive, research-grade answers with multi-step reasoning. The API autonomously plans a research strategy, executes multiple searches, reads and cross-references sources, and synthesizes everything into a Markdown answer with inline citations. At higher effort levels, a single query can run 1,000+ reasoning turns and process up to 10 million tokens.

**Request body (JSON):**

```json
{
  "input": "What are the environmental impacts of lithium mining?",
  "research_effort": "standard"
}
```

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| input | Yes | string | Research question or complex query (max 40,000 chars) |
| research_effort | No | string | `lite`, `standard` (default), `deep`, `exhaustive` |

**Research effort levels:**

| Level | Behavior | Typical Latency | Best For |
|-------|----------|-----------------|----------|
| `lite` | Quick answer, minimal searching | <2s | Simple factual questions, low-latency applications |
| `standard` | Balanced speed and depth | 10-30s | General-purpose questions, most applications (default) |
| `deep` | More searches, deeper cross-referencing | <120s | Multi-faceted questions, competitive analysis, due diligence |
| `exhaustive` | Maximum thoroughness, extensive verification | <300s | High-stakes research, regulatory compliance, comprehensive reports |

**Response:**

```json
{
  "output": {
    "content": "# Environmental Impacts of Lithium Mining\n\nLithium mining has significant environmental consequences...[1][2]...",
    "content_type": "text",
    "sources": [
      {
        "url": "https://example.com/lithium-impact",
        "title": "Environmental Impact of Lithium Extraction",
        "snippets": ["Lithium extraction in South America's lithium triangle requires..."]
      }
    ]
  }
}
```

The `content` field contains Markdown with inline citation numbers (e.g. `[1]`, `[2]`) that reference the `sources` array. Every claim is traceable to a specific source URL.

### Search API

**Base URL:** `https://api.you.com`
**Endpoint:** `GET /v1/agents/search`

Returns raw web and news results for a query. Allows 100 free searches/day without an API key. Use this when you need full control over result processing — feeding results into your own LLM, building custom UIs, or applying your own ranking/filtering.

**Query parameters:**

| Parameter | Required | Type | Description |
|-----------|----------|------|-------------|
| query | Yes | string | Search terms; supports [search operators](https://docs.you.com/search/search-operators) |
| count | No | integer | Results per section (1-100, default: 10) |
| freshness | No | string | `day`, `week`, `month`, `year`, or `YYYY-MM-DDtoYYYY-MM-DD` |
| offset | No | integer | Pagination (0-9). Calculated in multiples of `count` |
| country | No | string | Country code (e.g. `US`, `GB`, `DE`) |
| language | No | string | BCP 47 language code (default: `EN`) |
| safesearch | No | string | `off`, `moderate`, `strict` |
| livecrawl | No | string | `web`, `news`, `all` — enables full content retrieval inline |
| livecrawl_formats | No | array of strings | `html` and/or `markdown` (requires livecrawl) |
| include_domains | No | array of strings | Domains to include in results (up to 500) |
| exclude_domains | No | array of strings | Domains to exclude from results (up to 500) |
| crawl_timeout | No | integer | Timeout in seconds for livecrawl (1-60, default: 10) |

**Response structure:**

```json
{
  "results": {
    "web": [
      {
        "url": "https://example.com",
        "title": "Page Title",
        "description": "Snippet text",
        "snippets": ["..."],
        "thumbnail_url": "https://...",
        "page_age": "2025-06-25T11:41:00",
        "authors": ["John Doe"],
        "favicon_url": "https://example.com/favicon.ico",
        "contents": { "html": "...", "markdown": "..." }
      }
    ],
    "news": [
      {
        "title": "News Title",
        "description": "...",
        "url": "https://...",
        "page_age": "2025-06-25T11:41:00",
        "thumbnail_url": "https://...",
        "contents": { "html": "...", "markdown": "..." }
      }
    ]
  },
  "metadata": {
    "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
    "query": "...",
    "latency": 0.123
  }
}
```

### Contents API

**Base URL:** `https://ydc-index.io`
**Endpoint:** `POST /v1/contents`

Retrieves full webpage content in multiple formats. Use after Search to deep-read specific pages, or independently to extract content from known URLs.

**Request body (JSON):**

```json
{
  "urls": ["https://example.com/page1", "https://example.com/page2"],
  "formats": ["markdown", "metadata"],
  "crawl_timeout": 10
}
```

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| urls | Yes | array of strings | URLs to fetch |
| formats | No | array | `html`, `markdown`, `metadata` |
| crawl_timeout | No | integer | Timeout in seconds (1-60, default: 10) |

**Response:**

```json
[
  {
    "url": "https://example.com/page1",
    "title": "Page Title",
    "html": "<html>...</html>",
    "markdown": "# Page Title\n...",
    "metadata": {
      "site_name": "Example",
      "favicon_url": "https://example.com/favicon.ico"
    }
  }
]
```

---

## Path A: Research API

The fastest way to add web-grounded, cited answers to any application. One API call replaces an entire search-read-synthesize pip