> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://you.com/docs/_mcp/server. # Search POST https://ydc-index.io/v1/search Content-Type: application/json This endpoint is designed to return LLM-ready web results based on a user's query. Based on a classification mechanism, it can return web results and news associated with your query. If you need to feed an LLM with the results of a query that sounds like `What are the latest geopolitical updates from India`, then this endpoint is the right one for you. `POST` is the recommended method when using complex parameters such as `include_domains`, `exclude_domains`, or `boost_domains`. These fields accept JSON arrays in the request body, which is unambiguous and avoids URL length limits. Use GET for simple queries where HTTP cacheability matters. Reference: https://you.com/docs/api-reference/search/v1-search ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: search version: 1.0.0 paths: /v1/search: post: operationId: search-post summary: Returns a list of unified search results from web and news sources description: >- This endpoint is designed to return LLM-ready web results based on a user's query. Based on a classification mechanism, it can return web results and news associated with your query. If you need to feed an LLM with the results of a query that sounds like `What are the latest geopolitical updates from India`, then this endpoint is the right one for you. `POST` is the recommended method when using complex parameters such as `include_domains`, `exclude_domains`, or `boost_domains`. These fields accept JSON arrays in the request body, which is unambiguous and avoids URL length limits. Use GET for simple queries where HTTP cacheability matters. tags: - '' parameters: - name: X-API-Key in: header description: >- A unique API Key is required to authorize API access. [Get your API Key with free credits](https://you.com/platform). required: true schema: type: string responses: '200': description: >- A JSON object containing unified search results from web and news sources content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '401': description: Unauthorized. Problems with API key. content: application/json: schema: $ref: '#/components/schemas/SearchPostRequestUnauthorizedError' '403': description: Forbidden. API key lacks scope for this path. content: application/json: schema: $ref: '#/components/schemas/SearchPostRequestForbiddenError' '422': description: Unprocessable Entity. Invalid request parameter combination. content: application/json: schema: $ref: '#/components/schemas/SearchPostRequestUnprocessableEntityError' '500': description: >- Internal Server Error during authentication/authorization middleware. content: application/json: schema: $ref: '#/components/schemas/SearchPostRequestInternalServerError' requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchRequestBody' servers: - url: https://ydc-index.io description: Production components: schemas: SearchQuery: type: string description: >- The search query used to retrieve relevant results from the web. You can also include [search operators](https://you.com/docs/search/search-operators) to refine your search. title: SearchQuery Count: type: integer default: 10 description: >- Specifies the maximum number of search results to return per section (the sections are `web` and `news`. See the JSON response to visualize them). title: Count Freshness: type: string enum: - day - week - month - year title: Freshness FreshnessValue: oneOf: - $ref: '#/components/schemas/Freshness' - type: string description: >- Specifies the freshness of the results to return. Provide either one of `day`, `week`, `month`, `year`, or a date range string in the format `YYYY-MM-DDtoYYYY-MM-DD`. When your search query includes a temporal keyword and you also set a freshness parameter, the search will use the broader (i.e., less restrictive) of the two timeframes. For example, if you use `query=news+this+week&freshness=month`, the results will use a freshness of month. title: FreshnessValue Offset: type: integer default: 0 description: >- Indicates the `offset` for pagination. The `offset` is calculated in multiples of `count`. For example, if `count = 5` and `offset = 1`, results 5–10 will be returned. Range `0 ≤ offset ≤ 9`. title: Offset Country: type: string enum: - AR - AU - AT - BE - BR - CA - CL - DK - FI - FR - DE - HK - IN - ID - IT - JP - KR - MY - MX - NL - NZ - 'NO' - CN - PL - PT - PH - RU - SA - ZA - ES - SE - CH - TW - TR - GB - US description: >- The country code that determines the geographical focus of the web results. title: Country Language: type: string enum: - AR - EU - BN - BG - CA - ZH-HANS - ZH-HANT - HR - CS - DA - NL - EN - EN-GB - ET - FI - FR - GL - DE - EL - GU - HE - HI - HU - IS - IT - JA - KN - KO - LV - LT - MS - ML - MR - NB - PL - PT-BR - PT-PT - PA - RO - RU - SR - SK - SL - ES - SV - TA - TE - TH - TR - UK - VI default: EN description: The language of the web results that will be returned (BCP 47 format). title: Language SafeSearch: type: string enum: - 'off' - moderate - strict default: moderate description: >- Configures the safesearch filter for content moderation. This allows you to decide whether to return NSFW content or not. title: SafeSearch LiveCrawl: type: string enum: - web - news - all description: >- Passing a value will turn on live crawling, which returns the full page content of each result in the specified section(s). This may add latency to the request. **Pricing:** Livecrawl is billed at $1.00 per 1,000 pages, on top of the base Search API rate of $5.00 per 1,000 calls. This is the same per-page rate as the Contents API. For example, a single call with `count=10` and `livecrawl=all` crawls up to 20 pages (10 web + 10 news), adding $0.02 to the $0.005 base call cost. title: LiveCrawl LiveCrawlFormatsItems: type: string enum: - html - markdown title: LiveCrawlFormatsItems LiveCrawlFormats: type: array items: $ref: '#/components/schemas/LiveCrawlFormatsItems' description: >- Indicates the format(s) of the livecrawled content. Pass one or both values (`html`, `markdown`). In a GET request, repeat the parameter: `?livecrawl_formats=html&livecrawl_formats=markdown`. In a POST body, provide a JSON array: `["html", "markdown"]`. title: LiveCrawlFormats IncludeDomains: type: array items: type: string description: >- A list of domains to restrict search results to. Only results from these domains will be returned. Supports up to 500 domains. This is a strict allowlist, not a boost — results are limited exclusively to the specified domains. Cannot be combined with `exclude_domains`; passing both will return a `422` error. title: IncludeDomains ExcludeDomains: type: array items: type: string description: >- A list of domains to exclude from search results. Results from these domains will be filtered out. Supports up to 500 domains. Cannot be combined with `include_domains`; passing both will return a `422` error. title: ExcludeDomains BoostDomains: type: array items: type: string description: >- A list of domains to boost in search ranking. Matching results from these domains receive a fixed relative ranking boost, but this is not a filter. If the boosted domains do not have matching results, results from other domains can still appear. Supports up to 500 domains. Can be combined with `exclude_domains`. Cannot be combined with `include_domains`. Passing both `boost_domains` and `include_domains` will return a `422` error. title: BoostDomains CrawlTimeout: type: integer default: 10 description: >- Maximum time in seconds to wait for page content when `livecrawl` is enabled. Must be between 1 and 60 seconds. Default is 10 seconds. title: CrawlTimeout SearchRequestBody: type: object properties: query: $ref: '#/components/schemas/SearchQuery' count: $ref: '#/components/schemas/Count' freshness: $ref: '#/components/schemas/FreshnessValue' offset: $ref: '#/components/schemas/Offset' country: $ref: '#/components/schemas/Country' language: $ref: '#/components/schemas/Language' safesearch: $ref: '#/components/schemas/SafeSearch' livecrawl: $ref: '#/components/schemas/LiveCrawl' livecrawl_formats: $ref: '#/components/schemas/LiveCrawlFormats' include_domains: $ref: '#/components/schemas/IncludeDomains' exclude_domains: $ref: '#/components/schemas/ExcludeDomains' boost_domains: $ref: '#/components/schemas/BoostDomains' crawl_timeout: $ref: '#/components/schemas/CrawlTimeout' required: - query title: SearchRequestBody Contents: type: object properties: html: type: string description: The HTML content of the page. markdown: type: string description: The Markdown content of the page. description: Contents of the page if livecrawl was enabled. title: Contents WebResult: type: object properties: url: type: string description: The URL of the specific search result. title: type: string description: The title or name of the search result. description: type: string description: A brief description of the content of the search result. snippets: type: array items: type: string description: >- An array of text snippets from the search result, providing a preview of the content. thumbnail_url: type: string description: URL of the thumbnail. page_age: type: string format: date-time description: The age of the search result. contents: $ref: '#/components/schemas/Contents' authors: type: array items: type: string description: An array of authors of the search result. favicon_url: type: string description: The URL of the favicon of the search result's domain. title: WebResult NewsResult: type: object properties: title: type: string description: The title of the news result. description: type: string description: A brief description of the content of the news result. page_age: type: string format: date-time description: UTC timestamp of the article's publication date. thumbnail_url: type: string description: URL of the thumbnail. url: type: string description: The URL of the news result. contents: $ref: '#/components/schemas/Contents' title: NewsResult SearchResponseResults: type: object properties: web: type: array items: $ref: '#/components/schemas/WebResult' news: type: array items: $ref: '#/components/schemas/NewsResult' title: SearchResponseResults SearchMetadata: type: object properties: search_uuid: type: string format: uuid query: type: string description: Returns the search query used to retrieve the results. latency: type: number format: double title: SearchMetadata SearchResponse: type: object properties: results: $ref: '#/components/schemas/SearchResponseResults' metadata: $ref: '#/components/schemas/SearchMetadata' title: SearchResponse SearchPostRequestUnauthorizedError: type: object properties: detail: type: string description: Error detail message. title: SearchPostRequestUnauthorizedError SearchPostRequestForbiddenError: type: object properties: detail: type: string title: SearchPostRequestForbiddenError SearchPostRequestUnprocessableEntityError: type: object properties: error: type: string title: SearchPostRequestUnprocessableEntityError SearchPostRequestInternalServerError: type: object properties: detail: type: string title: SearchPostRequestInternalServerError securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- A unique API Key is required to authorize API access. [Get your API Key with free credits](https://you.com/platform). ``` ## Examples **Request** ```json { "query": "What are the latest geopolitical updates from India", "count": 10, "include_domains": [ "timesofindia.indiatimes.com", "ndtv.com", "thehindu.com" ] } ``` **Response** ```json { "results": { "web": [ { "url": "https://timesofindia.indiatimes.com/topic/geopolitics/news", "title": "Geopolitics News | Latest News on Geopolitics - Times of India", "description": "European nations, particularly Denmark and Norway, are scrutinizing Chinese-made Yutong buses over security fears. Operators worry that 'over-the-air' software updates could allow remote immobilization of the fleet, mirroring concerns over Chinese tech in 5G networks. This potential vulnerability, inherent in connected vehicles, raises geopolitical questions about reliance on foreign manufacturers. India ...", "snippets": [ "European nations, particularly Denmark and Norway, are scrutinizing Chinese-made Yutong buses over security fears. Operators worry that 'over-the-air' software updates could allow remote immobilization of the fleet, mirroring concerns over Chinese tech in 5G networks. This potential vulnerability, inherent in connected vehicles, raises geopolitical questions about reliance on foreign manufacturers. India secures 3rd place in Oz think tank's Asia Power Index", "Nations like New Zealand, parts of Australia, Iceland, and select South American and African countries are frequently cited as potentially more resilient to widespread conflict and its devastating aftermath. India-EU summit: FTA, defence and connectivity among key outcomes, EU seeks Paris commitment ... Pheasant Island, a tiny river island between Spain and France, uniquely swaps sovereignty every six months. This geopolitical gem's alternating control stems from the 1659 Treaty of the Pyrenees, a testament to centuries of cooperation.", "Check out for the latest news on geopolitics along with geopolitics live news at Times of India", "Despite massive viewership, he feels his content tackling geopolitical issues is too risky for corporate partners, leading him to expect no further wins. Economy enters H2 on stable footing: Finance ministry ... India's economy enters the second half of FY26 on a stable footing, supported by contained inflation, resilient domestic demand, and supportive policies. While global uncertainties pose risks to exports and capital flows, strong public capital expenditure and firming rural and urban demand are expected to maintain growth momentum." ], "thumbnail_url": "https://static.toiimg.com/photo/47529300.cms", "favicon_url": "https://you.com/favicon?domain=timesofindia.indiatimes.com&size=128" }, { "url": "https://www.ndtv.com/topic/geopolitical", "title": "Geopolitical: Latest News, Photos, Videos on Geopolitical - NDTV.COM", "description": "Find Geopolitical Latest News, Videos & Pictures on Geopolitical and see latest updates, news, information from NDTV.COM. Explore more on Geopolitical.", "snippets": [ "Gold surged above $4,000 an ounce to hit a record on Wednesday, driven by investors seeking safety from mounting economic and geopolitical uncertainty, alongside expectations of further interest rate cuts by the US Federal Reserve. In a landmark development that could reshape regional geopolitics, Afghan Foreign Minister Amir Khan Muttaqi of the Taliban government is all set to visit India on October 9.", "IndiGo flight 6E1703 from Kolkata touched down in the southern Chinese city of Guangzhou shortly before 4:00 am, officially resuming nonstop air links that had been suspended since 2020 due to the pandemic and subsequent geopolitical tensions.", "China's new visa programme aimed at attracting foreign tech talent launches this week, a move seen boosting Beijing's fortunes in its geopolitical rivalry with Washington as a new US visa policy prompts would-be applicants to search for alternatives.", "India's defence manufacturing is not only about Atmanirbharta, but also about making in India and selling to the world, according to industry leaders at the NDTV Defence Summit 2025." ], "thumbnail_url": "https://cdn.ndtv.com/common/images/ogndtv.png", "favicon_url": "https://you.com/favicon?domain=www.ndtv.com&size=128" } ], "news": [ { "title": "India entering golden era of defence innovation: Rajnath", "description": "New Delhi, Nov 25 (PTI) Amid a rapidly changing world and evolving geopolitics, India must move beyond a reactive approach and adopt a \"proactive\" outlook to make itself future-ready, Defence Minister Rajnath Singh said on Tuesday.", "page_age": "2025-11-25T12:31:29", "thumbnail_url": "https://static.theprint.in/wp-content/uploads/2023/06/theprint_default_image_new.jpg", "url": "https://theprint.in/india/india-entering-golden-era-of-defence-innovation-rajnath/2791865/" }, { "title": "India-Pakistan Tensions: Geopolitical Fallout and Regional Stability", "description": "As tensions between India and Pakistan persist following recent military exchanges, analysts assess the broader geopolitical implications for South Asia and global powers.", "page_age": "2025-11-20T08:15:00", "thumbnail_url": "https://cdn.ndtv.com/common/images/ogndtv.png", "url": "https://www.ndtv.com/india-news/india-pakistan-tensions-geopolitical-fallout-2025" } ] }, "metadata": { "search_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query": "What are the latest geopolitical updates from India", "latency": 0.6842031478881836 } } ``` **SDK Code** ```python # Use our official Python SDK to run a web search with domain filtering from youdotcom import You with You("api_key") as you: results = you.search.unified( query="What are the latest geopolitical updates from India", count=10, include_domains=["timesofindia.indiatimes.com", "ndtv.com", "thehindu.com"] ) # Print web results with snippets # Snippets are query-relevant text excerpts extracted from each page, # highlighting the passages most relevant to your search query if results.results and results.results.web: for result in results.results.web: print(f"{result.title}") if result.snippets: print(f" {result.snippets[0]}\n") ``` ```typescript // Use our official TypeScript SDK to run a web search with domain filtering import { You } from "@youdotcom-oss/sdk"; import type { SearchPostRequest } from "@youdotcom-oss/sdk/models/operations"; const you = new You({ apiKeyAuth: "api_key" }); const request: SearchPostRequest = { query: "What are the latest geopolitical updates from India", includeDomains: ["timesofindia.indiatimes.com", "ndtv.com", "thehindu.com"], }; const result = await you.searchPost(request); console.log(result.metadata); console.log(result.results?.web); ``` ```javascript // Use our official JavaScript SDK to run a web search with domain filtering import { You } from "@youdotcom-oss/sdk"; const you = new You({ apiKeyAuth: "api_key" }); const request = { query: "What are the latest geopolitical updates from India", includeDomains: ["timesofindia.indiatimes.com", "ndtv.com", "thehindu.com"], }; const result = await you.searchPost(request); console.log(result.metadata); console.log(result.results?.web); ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://ydc-index.io/v1/search" payload := strings.NewReader("{\n \"query\": \"What are the latest geopolitical updates from India\",\n \"count\": 10,\n \"include_domains\": [\n \"timesofindia.indiatimes.com\",\n \"ndtv.com\",\n \"thehindu.com\"\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://ydc-index.io/v1/search") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"query\": \"What are the latest geopolitical updates from India\",\n \"count\": 10,\n \"include_domains\": [\n \"timesofindia.indiatimes.com\",\n \"ndtv.com\",\n \"thehindu.com\"\n ]\n}") .asString(); ``` ```csharp using RestSharp; var client = new RestClient("https://ydc-index.io/v1/search"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"query\": \"What are the latest geopolitical updates from India\",\n \"count\": 10,\n \"include_domains\": [\n \"timesofindia.indiatimes.com\",\n \"ndtv.com\",\n \"thehindu.com\"\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "query": "What are the latest geopolitical updates from India", "count": 10, "include_domains": ["timesofindia.indiatimes.com", "ndtv.com", "thehindu.com"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://ydc-index.io/v1/search")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```