Choose the Right API
Pick the card that matches what your code needs back. Every API except the Inference Router takes the same X-API-Key header, so switching later is a URL and payload change. The Inference Router takes Authorization: Bearer.
Match the Job
Compare the APIs
Pricing is pay-as-you-go. Billing has the full tables, including how cached pages change the full page charge.
Latency and Price by Effort Tier
The Research API and Finance Research API trade latency for depth through research_effort. Pick the lowest tier that answers the question.
Research API
Finance Research API
A synchronous request holds the connection for the full run. Set your HTTP client timeout above the tier’s upper bound—longer than 120s for deep and 300s for exhaustive—or send background: true and collect the result with background requests.
Details That Change the Choice
Web Search API: highlights, snippets, or full page
Set extraction_mode: "highlights" when an agent or RAG prompt needs query-relevant passages. Raw POST /v1/search returns snippets when you omit extraction, which suits a results UI. The Python SDK 3.6.0 and later sends highlights unless you pass knowledge=None and extraction=None, as the Web Search API Quickstart shows. Set extraction_mode: "full_page" when you need the whole page, billed at $1.00 per 1,000 pages fetched live on top of the search call. Page Content Extraction covers all three.
Contents API: skip search when you have the URL
Call the Contents API directly when your pipeline already knows the URLs. Adding a Web Search API call first only makes sense when you need URL discovery.
Answer API or Research API
The Answer API runs one search pass with no effort tiers, so cost and latency stay flat across queries. Move to the Research API when the question needs multiple searches, domain filters through source_control, or structured JSON through output_schema. output_schema is not available with lite, and frontier requires background: true.
Research API or Finance Research API
The Finance Research API returns the same response shape as the Research API. It accepts deep or exhaustive effort and the same output_schema for structured JSON, but does not accept source_control. Use it for filings, prices, fundamentals, and financial news.
REST or MCP
Call the REST APIs when your code owns the HTTP client, retries, and response parsing. Connect the MCP Server when an agent or IDE should decide when to call You.com. Product MCP has no you-answer tool, so agents that need a one-pass cited answer call the Answer API over REST. Build With Agents compares the Product MCP server, the Docs MCP Server, and Agent Skills.
TypeScript and JavaScript have three paths. Use fetch against the REST APIs when the application needs the JSON. Use @youdotcom-oss/mcp, or the hosted server at https://api.you.com/mcp, when an agent should call the tools. Use the Python SDK when you want a typed client that tracks new API fields. The @youdotcom-oss/sdk package is deprecated.
Endpoints and References
Each API has its own endpoint. Every request sends your API key in the X-API-Key header, except Inference Router requests, which send it as Authorization: Bearer.
The Inference Router, Answer, Research, and Finance Research APIs run only on api.you.com. Sending one of those paths to ydc-index.io returns 403 with {"message": "Missing Authentication Token"}, even when the key is valid.
The MCP Server is a separate endpoint, https://api.you.com/mcp, and authenticates with Authorization: Bearer or OAuth. Build With Agents covers setup.
The Quickstart runs a first request against each API.