How to Call the You.com Web Search API With cURL

TLDR: You can test the You.com Web Search API from a terminal in under a minute with a single cURL request. This guide shows the exact endpoint, the authentication header, a working request, what each response field means, and the mistakes that cause empty results, from unescaped operators to caching surprises. Everything here is drawn from the official API reference, so you can trust the parameter names.

What does a cURL request to the You.com Web Search API look like? It is one POST call to https://ydc-index.io/v1/search with two headers and a JSON body. The response is structured JSON with separate web and news sections, ready for scripts or a pipe into jq.

What Is the You.com Web Search API?

The Web Search API returns unified results from web and news sources in a single request. Every result carries a snippet or highlight, a clean description, a source URL, and metadata like publication dates. It is built for applications that need search data programmatically, not a scraped results page. If you want the full picture, the search API pillar article covers the architecture and use cases. For per-page extraction of specific URLs, the Contents API is the right tool instead.

How Do You Authenticate a cURL Request?

Authentication uses a single header, X-API-Key, whose value is the API key from your You.com platform account. There is no OAuth dance, no bearer token, and no signature to compute. That simplicity is exactly why cURL works so well as a first test.

export YDC_API_KEY="your-key-here"
curl -s -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the latest geopolitical updates from India", "count": 10}' \
  | jq '.results.web[0:3]'

Keeping the key in an environment variable keeps it out of your shell history. The -s flag silences the progress meter so the JSON is the only output. Save the snippet above as search.sh and you have a reusable search command for any terminal session.

What Parameters Can You Pass?

The request body takes one required parameter, query, and a set of optional parameters documented in the API reference: count (1 to 100 results per section), freshness for date filtering, country for geographic focus, language in BCP 47 format, offset for pagination (0 to 9), safesearch, include_domains, exclude_domains, and boost_domains. A worked cURL example with several parameters at once:

curl -s -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "site:reuters.com interest rate decision",
    "count": 5,
    "freshness": "week",
    "country": "US"
  }' | jq '.results.web[] | {title, url, description}'

Notice the site: operator inside the query string. Search operators are supported natively, including filetype:, +term and -term, and boolean AND, OR, NOT. For a deeper treatment of date filtering specifically, see the freshness guide, and for writing the same calls in Python, see the Python quickstart.

What Does the Response Look Like?

The response separates results into a web section and a news section, so a single call can serve both kinds of content without a second request. Each result includes a URL, a title, a description, a snippet or highlight, and metadata such as a publication date and thumbnail. A metadata object carries the search UUID, the query echo, and latency. The shape is flat JSON, which means jq filters like the ones above work without preprocessing. The Python quickstart maps every field in more detail.

What Breaks Most Often in cURL Requests?

Three failure modes account for nearly every broken first call. Each has a cheap fix, and each is a real signal about your integration, not just a typo.

Unescaped quotes in the query. A query like {"query": "what "AI" means"} produces invalid JSON and usually a 400 response. In cURL, keep double quotes out of the query text or escape them with a backslash. Detection is easy: pipe your body to jq . before sending it, and an invalid body will fail loudly right there.

Forgetting Content-Type. Without Content-Type: application/json, the server may not parse your body at all. This is the single most common cause of a 400 on a request that looks perfectly fine in every other way.

Expecting GET semantics. A GET request to the search endpoint still returns results for existing integrations, but the official reference centers POST, and newer parameters like extraction are POST only. If you copied a GET example from an old tutorial, rewrite it as POST before debugging anything else.

How Do You Paginate Results in cURL?

Pagination uses the offset parameter, which ranges from 0 to 9 and is calculated in multiples of count. If count is 5 and offset is 1, you get results 5 through 10. A simple loop that walks the first three pages:

for offset in 0 1 2; do
  curl -s -X POST https://ydc-index.io/v1/search \
    -H "X-API-Key: $YDC_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"query\": \"renewable energy policy\", \"count\": 10, \"offset\": $offset}" \
    | jq '.results.web[] | {title, url}'
done

Two practical notes. First, the offset ceiling is 9, so a single query can page through at most ten windows of results. Second, deep pagination over a changing index can repeat or skip results between calls, so collect and deduplicate by URL in your script rather than assuming pages are disjoint snapshots.

How Do You Keep a cURL Script Robust?

A one-off test can ignore failure modes. A script you run on a schedule cannot. Three habits make cURL calls dependable: set a timeout, capture the HTTP status, and check for empty sections before processing.

http_code=$(curl -s -o /tmp/results.json -w "%{http_code}" \
  --max-time 30 \
  -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "quarterly earnings coverage", "count": 10, "freshness": "week"}')

if [ "$http_code" != "200" ]; then
  echo "Search failed with HTTP $http_code" >&2
  exit 1
fi

count=$(jq '.results.web | length' /tmp/results.json)
if [ "$count" = "0" ] || [ -z "$count" ]; then
  echo "No web results, check query operators and freshness window" >&2
  exit 0
fi
jq '.results.web[] | {title, url, description}' /tmp/results.json

The --max-time 30 flag, documented in the cURL man page, prevents a hung connection from wedging a cron job. The jq filters follow the syntax in the jq manual. The -w "%{http_code}" pattern separates transport success from application success, which matters when you are piping output into something else. And the empty-section check catches the quiet failure where the API returns a valid 200 with zero results because your query was over-constrained, for example a site: operator on a domain with no matching pages combined with a one-day freshness window.

When Should You Use cURL Instead of an SDK?

The tradeoff is directness against convenience. cURL is the right tool when you want to verify your key works, inspect a raw response, reproduce a support issue, or test one parameter change without touching application code. The official youdotcom Python SDK is the right tool when you are building a pipeline, because it handles retries, typed responses, and response models like Extraction and ExtractionMode for you. Use cURL to understand the surface, then graduate to an SDK to build on it. The You.com platform is where API keys are issued, and the API reference documents every parameter this article uses.