Skip to navigation

Simple Search

Your first API call in 2 minutes—fetch real-time web results in under 20 lines.

View as MarkdownOpen in Claude

If you’re new to the You.com API, this is the right place to begin. Before building RAG pipelines or research agents, you need to understand the foundation: the Search API. Send a query. Get back accurate web and news results.

The Search API gives you direct access to You.com’s search index—the same index that powers our Research API and our own search engine. You get titles, URLs, and descriptions for the most relevant pages on the web, fast. Then you decide what to do with them: filter them, rank them, display them in a UI, or feed them into a language model to synthesize an answer.

This example shows the simplest possible way to call it: a Python script and a small Next.js web app you can deploy to Vercel.


Try It Live

Run a real Search API request right here—no setup, no separate app to deploy. Open the Try It panel below, paste your API key, edit the query, and send it against the live endpoint.

POST
/v1/search
curl -X POST https://ydc-index.io/v1/search \
-H "X-API-Key: <apiKey>" \
-H "Content-Type: application/json" \
-d '{
"query": "what is the difference between JWT and session authentication",
"count": 10,
"extraction": {
"extraction_mode": "highlights"
}
}'
Response
{
"results": {
"web": [
{
"url": "https://blog.logto.io/token-based-authentication-vs-session-based-authentication",
"title": "JWT vs Session authentication · Logto blog",
"thumbnail_url": "https://uploads.strapi.logto.io/2/session_vs_jwt_authentication_213beab414.webp",
"page_age": "2024-12-18T00:00:00",
"contents": {
"highlights": [
"Session-based authentication requires the server to query a session store, which can be slow, especially if it relies on external or centralized databases. In contrast, JWT authentication is stateless, with all necessary information stored in the client token, and utilizing signature to ensure security. This eliminates the need for session management, making it faster and more scalable, especially in distributed systems",
"Session-based workflows follow a similar process. However, after authentication, user information is stored on the server within a session, while JWTs rely on tokens sent to the client for storage and subsequent use"
]
},
"favicon_url": "https://you.com/favicon?domain=blog.logto.io&size=128"
},
{
"url": "https://heynode.com/tutorial/what-difference-between-sessions-and-json-web-tokens-jwt-authentication/",
"title": "What Is the Difference Between Sessions and JSON Web Tokens (JWT) Authentication?",
"contents": {
"highlights": [
"The main difference between sessions and JWT is how they authorize access to data. Both methods usually use a standard POST request to authenticate username and password. Once the user is verified, they will have access to specific data. The JWT token contains all the information needed to grant them access, without doing a server call. Sessions store the session ID on the client side, but still have to talk to the server to grant authorization.",
"The 2 most popular authentication methods are JSON web tokens (JWT) and Sessions. JWT are stateless, storing all authorization data in a token on the client-side. They are easier to implement if your application uses multiple domains and back-ends. Sessions are a stateful method that work by assigning the user a session ID that gets stored in a client-side cookie."
]
},
"favicon_url": "https://you.com/favicon?domain=heynode.com&size=128"
}
]
},
"metadata": {
"search_uuid": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"query": "what is the difference between JWT and session authentication",
"latency": 0.7431029796600342
}
}

What You’ll Build

The simplest possible example of the You.com Search API—pass a query, get back web results. No agents, no chaining, no extra dependencies. The unified endpoint returns title, URL, and description for the top results, ready to feed an LLM or render in a UI.


Prerequisites

Install the Python SDK.

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.

pip install youdotcom # Python ≥ 3.10

Run It

The quickest way to see the API in action is the command line.

simple_search.py
"""Simple Search — the "hello world" of the You.com Search API."""
import sys
from youdotcom import You
# take query from command line args, or use a default
query = sys.argv[1] if len(sys.argv) > 1 else "best programming languages 2026"
# initialize the client with your API key
you = You()
# run the search
response = you.search(query=query, count=5)
# print each result
for result in response.results.web:
print(f"{result.title}")
print(f" {result.url}")
print(f" {result.description}")
print()

Run it:

export YDC_API_KEY="your-api-key-here"
python simple_search.py "what is retrieval augmented generation"

No query? No problem—the example falls back to a default one, so python simple_search.py works too.

What you get back:

Each result has a title, URL, and a short description pulled from the page—clean, structured, and ready to use:

Title: What is RAG (Retrieval-Augmented Generation)? | IBM
https://www.ibm.com/topics/retrieval-augmented-generation
RAG is an AI framework that combines the strengths of traditional information
retrieval systems with the capabilities of generative large language models.

Next Steps


Resources