--- name: youdotcom-api description: > Integrate You.com APIs (Research, Search, Contents) into any language using direct HTTP calls — no SDK required.

- MANDATORY TRIGGERS: YDC API, You.com API integration, ydc-api, direct API integration, no SDK, Research API, youdotcom API, you.com REST API

- Use when: developer wants to call You.com APIs directly without an SDK wrapper license: MIT compatibility: Any language with HTTP client support (curl, fetch, requests, httpx, etc.) allowed-tools: Read Write Edit Bash(pip:install) Bash(npm:install) Bash(bun:add) assets: - search.input.schema.json - search.output.schema.json - research.input.schema.json - research.output.schema.json - contents.input.schema.json - contents.output.schema.json user-invocable: true metadata: {"openclaw":{"emoji":"🌐","primaryEnv":"YDC_API_KEY"},"author":"youdotcom-oss","version":"3.0.1","category":"sdk-integration","keywords":"you.com,ydc,api,research,search,contents,http,rest,integration,no-sdk,citations"} ---

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 API key authentication.

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. 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 below)
4. What testing framework do you use?

---

API Reference

All APIs use the same authentication: X-API-Key header with the You.com API key. Users can 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 | search.output.schema.json | | Research | research.input.schema.json | research.output.schema.json | | Contents | contents.input.schema.json | 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):

{
  "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:

{
  "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://ydc-index.io Endpoint: GET /v1/search

Returns raw web and news results for a query. 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 | | 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 | string | html or markdown (requires livecrawl) | | crawl_timeout | No | integer | Timeout in seconds for livecrawl (1-60, default: 10) |

Response structure:

{
  "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):

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

...