How to Use the You.com Web Search API in TypeScript

TLDR: The official You.com TypeScript SDK wraps the Web Search API in typed objects, so a working search is an npm install and three lines. This guide covers installation, the first call, typed filters, response types, error handling, and the Node version requirement. Every type and parameter here comes from the SDK documentation on npm and the official API reference.

What is the web search api typescript pattern? Install the @youdotcom-oss/sdk package from npm, initialize a You client with your YDC_API_KEY, call you.search() with a query, and read typed results off the response. No manual HTTP, no response parsing, no retry wiring.

How Do You Install the You.com TypeScript SDK?

The SDK is published on npm as @youdotcom-oss/sdk. Install it with your package manager of choice: npm add @youdotcom-oss/sdk, or the equivalent add command in pnpm, yarn, or bun. The package is maintained in the open-source youdotcom-typescript-sdk repository on GitHub, with typed examples for every endpoint.

Get an API key from the You.com platform, then set it as YDC_API_KEY in your environment. That single variable is all the configuration a first call needs.

What Does a First Search Call Look Like?

Initialize the client with the key, then call you.search().

import { You } from "@youdotcom-oss/sdk";

const you = new You({
 apiKeyAuth: process.env.YDC_API_KEY,
});

async function main() {
 const results = await you.search({
   query: "latest AI developments",
 });
 console.log(results);
}

main();


The response comes back as a typed SearchResponse object, with the web results in results.web and, when the query has news intent, news results in results.news. Each result carries url, title, and description, and news results add page_age for the publication timestamp.

How Do You Pass Typed Filters?

The SDK exports enums for the filter values, so the compiler catches typos before a request ever ships.

import { You } from "@youdotcom-oss/sdk";
import { Freshness, Country } from "@youdotcom-oss/sdk/models";

const you = new You({
 apiKeyAuth: process.env.YDC_API_KEY,
});

async function main() {
 const results = await you.search({
   query: "renewable energy",
   count: 10,
   freshness: Freshness.Week,
   country: Country.Us,
 });
 console.log(results);
}

main();


The underlying parameter set matches the API reference: count up to 100 results per section, freshness for recency windows, country as an ISO 3166-1 alpha-2 code, language as a BCP 47 code, offset for pagination from 0 to 9, safesearch with off, moderate (default), or strict, and include_domains, exclude_domains, and boost_domains for domain steering, up to 500 domains each. The include and boost filters cannot be combined.

How Do You Page Through and Filter Domains?

Pagination and domain steering are the two calls that come up next in real projects. offset pages results from 0 to 9, in multiples of count, so count: 5 with offset: 1 returns results 5 through 10. Domain filters take string arrays on POST.

import { You } from "@youdotcom-oss/sdk";

const you = new You({
 apiKeyAuth: process.env.YDC_API_KEY,
});

async function pageOne() {
 return you.search({
   query: "web search api",
   count: 10,
   offset: 1,
   include_domains: ["reuters.com", "arstechnica.com"],
   exclude_domains: ["pinterest.com"],
 });
}


Deduplicate by URL across pages, since an index that shifts between requests can overlap adjacent pages. And keep in mind the one documented constraint on the domain filters: include_domains and boost_domains cannot be combined in one request.

What Types Does the Response Use?

The SDK ships a SearchResponse model documented in the repository, and the result objects under results.web and results.news mirror the API's response fields. Because the types are generated against the published spec, your editor's autocomplete is the documentation. When you want the full field list, the API reference is the source of truth, and the SDK's model docs list every property.

How Do You Handle Errors Without Guessing?

Two responses cover most incidents. A 401 means the key is missing, malformed, or rotated, and the fix is the environment: confirm YDC_API_KEY is set in the process running your code, not only your interactive shell. A 429 means you hit the rate limit, and the response carries headers that specify retry behavior, so honor them with exponential backoff rather than a fixed sleep. Wrap the call site so a failed search degrades gracefully instead of crashing the request path that depends on it.

async function searchWithFallback(
 you: You,
 query: string,
): Promise<SearchResponse | null> {
 try {
   return await you.search({ query });
 } catch (err) {
   console.error("search failed", err);
   return null;
 }
}


The error code reference documents every status code with causes and recommended actions.

How Do You Handle Timeouts and Retries?

Search calls are fast, but any network call can hang. Node's fetch and the SDK both respect a signal or timeout option, so set one at the call site rather than letting a stalled request hold your event loop's promise chain open. A 10-second ceiling is a reasonable starting point for a search, and you can tighten it for latency-sensitive paths.

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10_000);

try {
 const results = await you.search(
   { query: "latest AI developments" },
   // pass the abort signal through your HTTP layer
   { signal: controller.signal },
 );
 console.log(results.results?.web?.[0]?.title);
} finally {
 clearTimeout(timeout);
}


For retries, distinguish error classes. A 429 means back off and retry, honoring the retry guidance in the response headers. A 401 means stop and fix the key, since retrying sends the same bad credential. A timeout is worth one retry, then surface the failure to the caller rather than hiding it behind stale defaults.

Should You Use the SDK or Raw Fetch?

Use the SDK unless you have a reason not to. It handles request encoding, typed response models, and error classes, and it is the package maintained against the live API surface. Raw fetch calls against https://ydc-index.io/v1/search work and are useful for testing, but you take on response parsing and drift risk yourself. Teams that standardize on the SDK get compiler-checked parameters for free.

One middle path is worth naming. Start raw, then adopt the SDK once your usage grows. A throwaway fetch script confirms the key and the response shape in minutes. When the second call site appears, that script becomes the SDK call, because a typed client is cheaper than maintaining your own hand-rolled types. The migration is small precisely because the request bodies are identical, and your existing tests transfer over with them.

Where Does This Fit With the Rest of the Stack?

The same SDK covers the other You.com APIs, so one dependency serves search, contents, and research workflows. A common TypeScript pattern: search with the Web Search API, then extract full page content for the results worth reading. The Contents API guide shows that second step. For framework integrations, the docs list ready-made paths for the Vercel AI SDK and LangChain.

Where Do You Go Next?

Install the SDK, run the first search call above with your key, and inspect the typed response in your editor. Then read the Python guide for the same patterns in that language, the cURL walkthrough for the raw HTTP surface, and the search API hub page for the full product picture. The You.com platform is where API keys are issued.