> 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 full documentation content, see https://you.com/docs/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`, `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
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
        - 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
    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).

```

## 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()
```