{"openapi":"3.1.0","info":{"title":"Web Search","version":"1.0.0"},"paths":{"/v1/search":{"post":{"operationId":"searchPost","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.\n\nEach result can carry three levels of content. **Snippets** come back by default—short, keyword-centered fragments that suit a person skimming a results page, though an agent grounding an answer usually needs more. **Full page content** gives you everything, which can be a lot for the model to read. **Highlights** sit in between, returning the passages of a page that address the query and nothing else. These are query-aware and token-efficient excerpts, which matter most for agents that run several searches per task and read every result rather than the top few. Both are available through the new `extraction` parameter, as `extraction_mode: \"highlights\"` or `extraction_mode: \"full_page\"`.\n\n<Note> `GET /v1/search` still works and existing integrations will keep running, but it will not receive new feature updates. New features will be added to `POST` only, and `extraction` is only available here. </Note>","responses":{"200":{"description":"A JSON object containing unified search results from web and news sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPostResponse"}}}},"401":{"description":"Unauthorized. Problems with API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPostRequestUnauthorizedError"}}}},"402":{"description":"Payment Required. The account cannot make paid API requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpgradeRequiredResponse"}}}},"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"}}}},"security":[{"ApiKeyAuth":[]}]}}},"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/guides/search-operators) to refine your search.","title":"SearchQuery"},"Count":{"type":"integer","minimum":1,"maximum":100,"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`.\n\nWhen 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","minimum":0,"maximum":9,"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"},"Knowledge":{"type":"string","enum":["core"],"description":"Requests knowledge results alongside web and news search.","title":"Knowledge"},"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.\n\nCannot 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.\n\nCannot 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.\n\nCan 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"},"ExtractionExtractionMode":{"type":"string","enum":["highlights","full_page"],"description":"Specifies which kind of extraction to run.\n\n`highlights` returns the passages of each page that address your query in `contents.highlights`, sized for token-sensitive agent workflows.\n\n`full_page` crawls each result and returns the page content. Pass the optional `full_page` object to override its defaults.","title":"ExtractionExtractionMode"},"ExtractionExtractionSource":{"type":"string","enum":["blend","cache","fetch"],"default":"blend","description":"Indicates where `full_page` content comes from. Ignored when `extraction_mode` is `\"highlights\"`.\n\n`blend` serves cached content when it is available and crawls the page live when it is not. This is the default.\n\n`cache` returns cached content only. It is the fastest option, and `contents` is omitted for results that have no cached content.\n\n`fetch` always crawls the page live, which returns the freshest content at the cost of higher latency.","title":"ExtractionExtractionSource"},"FullPageConfigExtractionFormatsItems":{"type":"string","enum":["html","markdown"],"title":"FullPageConfigExtractionFormatsItems"},"FullPageConfig":{"type":"object","properties":{"extraction_formats":{"type":"array","items":{"$ref":"#/components/schemas/FullPageConfigExtractionFormatsItems"},"default":["markdown"],"description":"Content formats to return, one or both of `markdown` and `html`."}},"description":"Configures `extraction_mode: \"full_page\"`.","title":"FullPageConfig"},"Extraction":{"type":"object","properties":{"extraction_mode":{"$ref":"#/components/schemas/ExtractionExtractionMode","description":"Specifies which kind of extraction to run.\n\n`highlights` returns the passages of each page that address your query in `contents.highlights`, sized for token-sensitive agent workflows.\n\n`full_page` crawls each result and returns the page content. Pass the optional `full_page` object to override its defaults."},"extraction_source":{"$ref":"#/components/schemas/ExtractionExtractionSource","default":"blend","description":"Indicates where `full_page` content comes from. Ignored when `extraction_mode` is `\"highlights\"`.\n\n`blend` serves cached content when it is available and crawls the page live when it is not. This is the default.\n\n`cache` returns cached content only. It is the fastest option, and `contents` is omitted for results that have no cached content.\n\n`fetch` always crawls the page live, which returns the freshest content at the cost of higher latency."},"full_page":{"$ref":"#/components/schemas/FullPageConfig"}},"required":["extraction_mode"],"description":"Specifies the content to extract from each search result. Omit `extraction` for a plain search that returns snippets only. Available on `POST /v1/search` only, and supersedes the deprecated `livecrawl` and `livecrawl_formats` parameters.\n\n**Pricing:** This feature may add additional cost depending on your configuration. See [billing](https://you.com/docs/administration/billing#web-search-api) for all details.","title":"Extraction"},"LiveCrawl":{"type":"string","enum":["web","news","all"],"description":"Deprecated. Still works on both `GET` and `POST /v1/search` but is no longer developed. Use the `extraction` object on `POST /v1/search` instead—it supersedes `livecrawl` and returns query-relevant `highlights` or full-page content.\nPassing 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.\n\n**Pricing:** This feature may add additional cost depending on your configuration. See [billing](https://you.com/docs/administration/billing#web-search-api) for all details.","title":"LiveCrawl","deprecated":true},"LiveCrawlFormatsItems":{"type":"string","enum":["html","markdown"],"title":"LiveCrawlFormatsItems"},"LiveCrawlFormats":{"type":"array","items":{"$ref":"#/components/schemas/LiveCrawlFormatsItems"},"description":"Deprecated. Use `extraction.full_page.extraction_formats` on `POST /v1/search` instead.\nIndicates the format(s) of the livecrawled content. Pass one or both values (`html`, `markdown`) by repeating the parameter: `?livecrawl_formats=html&livecrawl_formats=markdown`.","title":"LiveCrawlFormats","deprecated":true},"CrawlTimeout":{"type":"integer","minimum":1,"maximum":60,"default":10,"description":"Maximum time in seconds to wait for page content when the request crawls pages, as `extraction_mode: \"full_page\"` or the deprecated `livecrawl` does. 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","default":10},"freshness":{"$ref":"#/components/schemas/FreshnessValue"},"offset":{"$ref":"#/components/schemas/Offset","default":0},"country":{"$ref":"#/components/schemas/Country"},"language":{"$ref":"#/components/schemas/Language","default":"EN"},"safesearch":{"$ref":"#/components/schemas/SafeSearch","default":"moderate"},"knowledge":{"$ref":"#/components/schemas/Knowledge"},"include_domains":{"$ref":"#/components/schemas/IncludeDomains"},"exclude_domains":{"$ref":"#/components/schemas/ExcludeDomains"},"boost_domains":{"$ref":"#/components/schemas/BoostDomains"},"extraction":{"$ref":"#/components/schemas/Extraction"},"livecrawl":{"$ref":"#/components/schemas/LiveCrawl","deprecated":true},"livecrawl_formats":{"$ref":"#/components/schemas/LiveCrawlFormats","default":["html"],"deprecated":true},"crawl_timeout":{"$ref":"#/components/schemas/CrawlTimeout","default":10}},"required":["query"],"title":"SearchRequestBody"},"WebContentsPost":{"type":"object","properties":{"html":{"type":"string","description":"The HTML content of the page."},"markdown":{"type":"string","description":"The Markdown content of the page."},"highlights":{"type":"array","items":{"type":"string"},"description":"Query-relevant passages from the page."}},"description":"Contents of a web result. `html` and/or `markdown` is returned when the request extracts full page content, and `highlights` when it asks for highlights.","title":"WebContentsPost"},"WebResultPost":{"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 short, keyword-centered text fragments from the search result, built for skimming. Omitted when the request asks for `extraction_mode: \"highlights\"`, which returns the query-ranked `contents.highlights` instead."},"thumbnail_url":{"type":"string","description":"URL of the thumbnail."},"page_age":{"type":"string","description":"The age of the search result."},"contents":{"$ref":"#/components/schemas/WebContentsPost"},"favicon_url":{"type":"string","description":"The URL of the favicon of the search result's domain."}},"title":"WebResultPost"},"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, returned when the request retrieves full page content.","title":"Contents"},"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","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"},"KnowledgeAttribution":{"type":"object","properties":{"name":{"type":"string","description":"Data provider for the knowledge result."},"source_description":{"type":"string","description":"Description of the provider."}},"required":["name"],"title":"KnowledgeAttribution"},"KnowledgeResult":{"type":"object","properties":{"type":{"type":"string","description":"The kind of knowledge result retrieved. `answer` is the only value currently returned. Ignore a value you do not recognize rather than failing on it, since a new kind may populate a different set of fields."},"title":{"type":"string","description":"The title of the knowledge result."},"attribution":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeAttribution"},"description":"Display credit for the data behind the result. These are credits rather than citations: each entry names a provider and carries no URL."},"description":{"type":"string","description":"Description of the knowledge result, drawn from proprietary licensed data. Required on `type: answer` results."},"as_of":{"type":"string","description":"The date the result's underlying data covers, as `YYYY-MM-DD`. Optional, and omitted when the provider reports no date."}},"required":["type","title","attribution"],"description":"A single knowledge result. `type` identifies the kind of result and determines which fields it populates. `type`, `title`, and `attribution` are required on every kind.\n\nFor `type: answer`, the only kind currently returned, `description` is required and `as_of` is optional.","title":"KnowledgeResult"},"SearchPostResponseResults":{"type":"object","properties":{"web":{"type":"array","items":{"$ref":"#/components/schemas/WebResultPost"}},"news":{"type":"array","items":{"$ref":"#/components/schemas/NewsResult"}},"knowledge":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeResult"},"description":"Results backed by licensed data providers. Up to 25 are returned, limited to those relevant to the query. When none are relevant the key is omitted rather than returned as an empty array."}},"title":"SearchPostResponseResults"},"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"},"SearchPostResponse":{"type":"object","properties":{"results":{"$ref":"#/components/schemas/SearchPostResponseResults"},"metadata":{"$ref":"#/components/schemas/SearchMetadata"}},"title":"SearchPostResponse"},"SearchPostRequestUnauthorizedError":{"type":"object","properties":{"detail":{"type":"string","description":"Error detail message."}},"title":"SearchPostRequestUnauthorizedError"},"UpgradeRequiredResponse":{"type":"object","properties":{"error":{"type":"string","description":"The error code."},"message":{"type":"string","description":"A description of the error."},"upgrade_url":{"type":"string","description":"The URL for adding credits or upgrading the account."},"limit":{"type":"integer","description":"The usage limit, when available."},"used":{"type":"integer","description":"The usage consumed, when available."},"period":{"type":"string","description":"The usage period, when available."},"reset_at":{"type":"string","description":"The reset timestamp, when available."}},"required":["error","message","upgrade_url"],"title":"UpgradeRequiredResponse"},"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)."}}}}