For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://you.com/docs/api-reference/search/llms.txt. For full documentation content, see https://you.com/docs/api-reference/search/llms-full.txt.

# 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` or `exclude_domains`. These fields accept JSON arrays in the request body, which is unambiguous and supports up to 500 domains per request—something that would exceed URL length limits with GET. 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` or `exclude_domains`. These fields accept JSON arrays
        in the request body, which is unambiguous and supports up to 500 domains
        per request—something that would exceed URL length limits with GET. 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
components:
  schemas:
    SearchQuery:
      type: string
      description: >-
        The search query used to retrieve relevant results from the web. You can
        also include [search
        operators](https://docs.you.com/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
        - JP
        - 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.
      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
    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'
        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).

```

## SDK Code Examples

```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", "<apiKey>")
	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<String> response = Unirest.post("https://ydc-index.io/v1/search")
  .header("X-API-Key", "<apiKey>")
  .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", "<apiKey>");
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": "<apiKey>",
  "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()
```