> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://you.com/docs/llms.txt.
> For full documentation content, see https://you.com/docs/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://you.com/docs/_mcp/server.

# Developer guide

Learn how to best integrate and troubleshoot the You.com API using our SDKs and MCP server.

***

## Quick Links

Official Python SDK

Official TypeScript SDK

Model Context Protocol integration

HTTP error codes and solutions

Contact API support

***

## SDKs & Libraries

### Python SDK

* Full type hints and async support
* Automatic retry logic
* [View Documentation](/docs/sdks/python-sdk)

### JavaScript/TypeScript SDK

* Full type hints and async support
* Automatic retry logic
* [View Documentation](/docs/sdks/typescript-sdk)

### Model Context Protocol (MCP)

Integrate You.com search directly into agentic IDEs like Claude Code, Cursor, VS Code, and more:

* Quick setup with hosted server or local NPM package
* Works with 10+ popular development environments
* Real-time web search for AI assistants
* [View MCP Documentation](/docs/build-with-agents/mcp-server)

***

## Authentication

All API requests require authentication using an API key.

### Get your API Key

1. Visit the [You.com platform](https://you.com/platform)
2. Create a new API key
3. Copy and store it securely

### Using Your API Key

Include your API key in the request header:

```curl
curl --request GET \
  --url 'https://ydc-index.io/v1/search?query=example' \
  --header 'X-API-Key: api_key'
```

**Security Best Practice:** Never commit API keys to version control. Use environment variables or secure secret management systems.

***

## Rate Limits & Quotas

API usage is subject to rate limits based on your subscription tier:

* **Free Tier:** Limited requests per day
* **Paid Tiers:** Higher limits based on plan

Rate limit details are included in response headers:

* `X-RateLimit-Limit` - Total requests allowed
* `X-RateLimit-Remaining` - Requests remaining
* `X-RateLimit-Reset` - Time when limit resets (Unix timestamp)

When you exceed rate limits, you'll receive a `429 Too Many Requests` response.

**Handling Rate Limits:**

```python
import time
import requests

def make_request_with_retry(url, headers):
    response = requests.get(url, headers=headers)

    if response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        print(f"Rate limited. Retrying after {retry_after} seconds...")
        time.sleep(retry_after)
        return make_request_with_retry(url, headers)

    return response
```

For higher rate limits, [upgrade your plan](https://you.com/platform/upgrade) or contact [api@you.com](mailto:api@you.com).

***

## Best Practices

### 1. **Use SDKs When Possible**

SDKs handle authentication, retries, and error handling automatically:

```python
# ✅ Good: Using SDK
import os
from youdotcom import You

with You(api_key_auth=os.getenv("api_key")) as you:
    response = you.search.unified(query="example")

# ❌ Less ideal: Manual requests
import requests
response = requests.get(
    "https://ydc-index.io/v1/search",
    params={"query": "example"},
    headers={"X-API-Key": os.getenv("api_key")}
)
```

### 2. **Implement Exponential Backoff**

For retry logic, use exponential backoff to avoid overwhelming the API:

```python
import time
from youdotcom import You, errors

def exponential_backoff(attempt):
    return min(2 ** attempt, 60)  # Max 60 seconds

with You(api_key_auth="api_key") as you:
    for attempt in range(5):
        try:
            response = you.search.unified(query="test")
            break
        except errors.YouError as e:
            if e.status_code == 429 and attempt < 4:
                wait_time = exponential_backoff(attempt)
                time.sleep(wait_time)
            else:
                raise
```

### 3. **Cache When Appropriate**

Cache search results for frequently asked questions:

```python
from functools import lru_cache
from youdotcom import You

you = You(api_key_auth="api_key")

@lru_cache(maxsize=100)
def cached_search(query: str):
    return you.search.unified(query=query)
```

### 4. **Handle Errors Gracefully**

Always provide fallback behavior:

```python
from youdotcom import You, errors

with You(api_key_auth="api_key") as you:
    try:
        response = you.search.unified(query=user_query)
    except errors.YouError as e:
        if e.status_code == 401:
            print("Configuration error. Please check your API key.")
        elif e.status_code == 429:
            print("Too many requests. Please try again in a moment.")
        else:
            print(f"API error: {e.message}")
```

***

## Frequently Asked Questions

Visit [you.com/platform](https://you.com/platform) to create and manage API keys. You'll need to sign up for a You.com account and select a plan.

Rate limits vary by subscription tier. Free tier has limited daily requests, while paid tiers offer higher limits. Check your current usage and limits in the [API Console](https://you.com/platform).

Yes! The You.com API is production-ready. We recommend using our official SDKs, implementing proper error handling, and monitoring your usage to stay within rate limits.

Yes! Email [api@you.com](mailto:api@you.com) for technical support, feature requests, or partnership inquiries. For bugs or issues with SDKs, you can also open issues on our GitHub repositories.

Yes, the You.com API can be used for commercial projects. Check our [terms of service](https://you.com/legal/terms) for details, or contact [api@you.com](mailto:api@you.com) for enterprise licensing.

All API keys can be used for testing and development. We recommend using a separate API key for development vs. production to track usage independently.

***

## Additional Resources

Get started in 5 minutes

Complete endpoint documentation

Advanced search syntax