***

title: Developer guide
'og:title': You.com developer guide
'og:description': >-
Essential developer resources for You.com API including SDKs, MCP integration,
error handling, and support channels.
-------------------------------------

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

***

## Quick Links

<CardGroup cols={3}>
  <Card title="Python SDK" icon="fa-brands fa-python" href="/sdks/python-sdk">
    Official Python SDK
  </Card>

  <Card title="TypeScript SDK" icon="fa-brands fa-js" href="/sdks/typescript-sdk">
    Official TypeScript SDK
  </Card>

  <Card title="MCP server" icon="fa-regular fa-plug" href="/mcp-server/overview">
    Model Context Protocol integration
  </Card>

  <Card title="Error reference" icon="fa-regular fa-triangle-exclamation" href="/error-handling/error-code-reference">
    HTTP error codes and solutions
  </Card>

  <Card title="Get an API key" icon="fa-regular fa-key" href="https://you.com/platform/api-keys" />

  <Card title="Support" icon="fa-regular fa-life-ring" href="mailto:api@you.com">
    Contact API support
  </Card>
</CardGroup>

***

## SDKs & Libraries

### Python SDK

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

### JavaScript/TypeScript SDK

* Full type hints and async support
* Automatic retry logic
* Streaming support for agents
* [View Documentation](/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](/mcp-server/overview)

***

## Authentication

All API requests require authentication using an API key.

### Get your API Key

1. Visit the [You.com platform](https://you.com/platform/api-keys)
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: YOUR_API_KEY'
```

For [Agent](/agents) APIs, use Bearer token authentication:

```curl
curl -N \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.you.com/v1/agents/runs \
  -d '{"agent": "express", "input": "test", "stream": true}'
```

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

***

## 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("YOU_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("YOU_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="YOUR_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. **Use Streaming for Agents**

Provide better UX by streaming agent responses:

```python
from youdotcom import You
from youdotcom.models import ExpressAgentRunsRequest, ResponseOutputTextDelta

with You(api_key_auth="YOUR_API_KEY") as you:
    # ✅ Good: Stream responses for real-time feedback
    response = you.agents.runs.create(
        request=ExpressAgentRunsRequest(input="query", stream=True)
    )

    with response as stream:
        for chunk in stream:
            if isinstance(chunk.data, ResponseOutputTextDelta):
                print(chunk.data.response.delta, end="", flush=True)
```

### 4. **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="YOUR_API_KEY")

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

### 5. **Handle Errors Gracefully**

Always provide fallback behavior:

```python
from youdotcom import You, errors

with You(api_key_auth="YOUR_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

<AccordionGroup>
  <Accordion title="How do I get an API key?" icon="key">
    Visit [you.com/platform/api-keys](https://you.com/platform/api-keys) to create and manage API keys. You'll need to sign up for a You.com account and select a plan.
  </Accordion>

  <Accordion title="What are the rate limits?" icon="gauge">
    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/api-keys).
  </Accordion>

  <Accordion title="Can I use the API in production?" icon="check">
    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.
  </Accordion>

  <Accordion title="How do I create a Custom Agent?" icon="robot">
    Custom Agents must be created via the [You.com UI](https://you.com/agents). Once created, you'll receive an agent ID that can be used with the [Custom Agent API](/api-reference/agents/custom-agent/custom-agent-runs).
  </Accordion>

  <Accordion title="What's the difference between Search API and Agents?" icon="magnifying-glass">
    The Search API returns raw web results, while Agents synthesize information and provide natural language answers with citations. Use Search API for building custom UIs, and Agents for conversational experiences.
  </Accordion>

  <Accordion title="Do you offer technical support?" icon="life-ring">
    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.
  </Accordion>

  <Accordion title="Can I use this for commercial projects?" icon="briefcase">
    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.
  </Accordion>

  <Accordion title="Is there a sandbox environment for testing?" icon="flask">
    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.
  </Accordion>
</AccordionGroup>

***

## Additional Resources

<CardGroup cols={2}>
  <Card title="Quickstart guide" icon="fa-regular fa-play" href="/quickstart">
    Get started in 5 minutes
  </Card>

  <Card title="API reference" icon="fa-regular fa-book" href="/api-reference/agents/express-agent/express-agent-runs">
    Complete endpoint documentation
  </Card>

  <Card title="Search operators" icon="fa-regular fa-filter" href="/search/search-operators">
    Advanced search syntax
  </Card>

  <Card title="Agents overview" icon="fa-regular fa-robot" href="/agents">
    Learn about Express, Advanced, and Custom agents
  </Card>
</CardGroup>