You.com API Authentication

How Authentication Works

Every You.com API request requires an API key, passed in the X-API-Key header. Get a key from the Platform API Keys page.

curl -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "global birth rate trends"}'

For key creation, rotation, and revocation, see API Key Management. This page covers how a request is authenticated, not how the key itself is managed.

The YDC_API_KEY Convention

All code samples in these docs read the key from an environment variable named YDC_API_KEY. It is the canonical variable name across the docs, the SDKs, and every integration example. Set it once and the samples pick it up.

TypeScript, MCP, or the Python SDK

TypeScript and JavaScript have three paths. Use fetch against the REST APIs when the application needs the JSON. Use @youdotcom-oss/mcp, or the hosted server at https://api.you.com/mcp, when an agent should call the tools. Use the Python SDK when you want a typed client that tracks new API fields. The @youdotcom-oss/sdk package is deprecated.

export YDC_API_KEY="<YDC_API_KEY>"

import os
from youdotcom import You
with You(api_key_auth=os.environ["YDC_API_KEY"]) as you:
    results = you.search(query="global birth rate trends")

const response = await fetch("https://ydc-index.io/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.YDC_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "global birth rate trends" }),
});

Never hardcode the key in source. Keep it in an environment variable or a secrets manager, and add .env files to .gitignore.

Scopes and 403 Responses

API keys are scoped per product. A key without access to a given path returns 403 Forbidden with {"detail": "Missing required scopes"}—for example, calling /v1/contents with a key that only has Web Search API access.

If you need access to an API your current key does not cover, create a new key with the right scope from the Platform.

Keyless Access via the Free MCP Profile

You can try the Web Search API without an API key by connecting any MCP-enabled client to api.you.com/mcp?profile=free. That profile is keyless and exposes you-search and you-discover (100 queries per day). It does not include you-contents, you-research, you-finance, or you-balance. For setup, see the MCP Server guide.

For everything beyond evaluation, use an API key.