> 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 AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://you.com/docs/_mcp/server. # Answer POST https://api.you.com/v1/answer Content-Type: application/json Returns a synthesized natural-language answer with citations and the web sources used to generate it. Provide a `query` and optional `freshness`, `country`, and `language` parameters. Unknown or extra request fields are rejected. Reference: https://you.com/docs/api-reference/answer/v1-answer ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: answer version: 1.0.0 paths: /v1/answer: post: operationId: answer summary: Returns a synthesized answer with citations from web search results description: >- Returns a synthesized natural-language answer with citations and the web sources used to generate it. Provide a `query` and optional `freshness`, `country`, and `language` parameters. Unknown or extra request fields are rejected. tags: - '' parameters: - name: X-API-Key in: header description: >- The unique API Key required to authorize API access. Learn how to get yours in the ["Get your API key" section of the documentation](https://you.com/docs/quickstart#get-your-api-key). required: true schema: type: string responses: '200': description: >- A JSON object containing a synthesized answer with citations and supporting search results content: application/json: schema: $ref: '#/components/schemas/answer_Response_200' '401': description: Unauthorized. Problems with API key. content: application/json: schema: $ref: '#/components/schemas/AnswerRequestUnauthorizedError' '403': description: Forbidden. API key lacks scope for this path. content: application/json: schema: $ref: '#/components/schemas/AnswerRequestForbiddenError' '422': description: Unprocessable Entity. Invalid request parameter combination. content: application/json: schema: $ref: '#/components/schemas/AnswerRequestUnprocessableEntityError' '500': description: >- Internal Server Error during authentication/authorization middleware. content: application/json: schema: $ref: '#/components/schemas/AnswerRequestInternalServerError' requestBody: content: application/json: schema: type: object properties: query: type: string description: The question or prompt to answer. freshness: $ref: '#/components/schemas/Freshness' country: $ref: '#/components/schemas/Country' language: $ref: '#/components/schemas/Language' required: - query servers: - url: https://api.you.com description: Production components: schemas: Freshness0: type: string enum: - day - week - month - year title: Freshness0 Freshness: oneOf: - $ref: '#/components/schemas/Freshness0' - 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 timeframe. For example, if you use `query=news+this+week&freshness=month`, the results will use a freshness of month. title: Freshness 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 - JA - 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 AnswerSearchResult: type: object properties: url: type: string description: The URL of the source webpage. title: type: string description: The title of the source webpage. description: type: string description: A brief description of the content of the source page. snippets: type: array items: type: string description: >- Relevant excerpts from the source page that were used in generating the answer. thumbnail_url: type: string description: URL of the thumbnail image for the source page. page_age: type: string description: The publication date or age of the source page. favicon_url: type: string description: The URL of the favicon of the source page's domain. citations: type: array items: type: string description: >- Exact quotes from this source that were cited in the answer. Only present on items in the `sources` array. required: - url - title title: AnswerSearchResult answer_Response_200: type: object properties: answer: type: string description: >- The synthesized response with inline citations. The answer is formatted in Markdown and includes numbered citations that reference the sources in the sources array. sources: type: array items: $ref: '#/components/schemas/AnswerSearchResult' description: >- The web sources cited in the answer, ordered by source usage. May be empty if the answer didn't cite specific sources. results: type: array items: $ref: '#/components/schemas/AnswerSearchResult' description: >- The top web search results considered during answer synthesis. Does not include the `citations` field. required: - answer - sources title: answer_Response_200 AnswerRequestUnauthorizedError: type: object properties: detail: type: string description: Error detail message. title: AnswerRequestUnauthorizedError AnswerRequestForbiddenError: type: object properties: detail: type: string title: AnswerRequestForbiddenError V1AnswerPostResponsesContentApplicationJsonSchemaDetailItemsLocItems: oneOf: - type: string - type: integer title: V1AnswerPostResponsesContentApplicationJsonSchemaDetailItemsLocItems V1AnswerPostResponsesContentApplicationJsonSchemaDetailItemsInput: oneOf: - type: string - type: object additionalProperties: description: Any type description: The input value that caused the error. title: V1AnswerPostResponsesContentApplicationJsonSchemaDetailItemsInput V1AnswerPostResponsesContentApplicationJsonSchemaDetailItems: type: object properties: type: type: string description: The validation error type. loc: type: array items: $ref: >- #/components/schemas/V1AnswerPostResponsesContentApplicationJsonSchemaDetailItemsLocItems description: >- The location of the error as a path of segments (strings for field names, integers for byte offsets). msg: type: string description: A human-readable description of the error. input: $ref: >- #/components/schemas/V1AnswerPostResponsesContentApplicationJsonSchemaDetailItemsInput description: The input value that caused the error. ctx: type: object additionalProperties: description: Any type description: Additional context about the error. required: - type - loc - msg - input title: V1AnswerPostResponsesContentApplicationJsonSchemaDetailItems AnswerRequestUnprocessableEntityError: type: object properties: detail: type: array items: $ref: >- #/components/schemas/V1AnswerPostResponsesContentApplicationJsonSchemaDetailItems title: AnswerRequestUnprocessableEntityError AnswerRequestInternalServerError: type: object properties: detail: type: string title: AnswerRequestInternalServerError securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: >- The unique API Key required to authorize API access. Learn how to get yours in the ["Get your API key" section of the documentation](https://you.com/docs/quickstart#get-your-api-key). ``` ## Examples ### What causes the aurora borealis **Request** ```json { "query": "what causes the aurora borealis" } ``` **Response** ```json { "answer": "The aurora borealis is caused by charged particles ejected from the Sun—carried by the solar wind and often intensified by solar flares or coronal mass ejections—that travel to Earth, are funneled by Earth's magnetic field toward the polar regions, and collide with oxygen and nitrogen atoms in the upper atmosphere. These collisions excite the atoms, which then release photons of light, creating the visible northern lights. [[1, 2, 3]]", "sources": [ { "url": "https://www.jpl.nasa.gov/nmp/st5/SCIENCE/aurora.html", "title": "How Auroras Form", "snippets": [ "Auroras are brilliant ribbons of light weaving across Earth's northern or southern polar regions. These natural light shows are caused by magnetic storms that have been triggered by solar activity, such as solar flares or coronal mass ejections." ], "citations": [ "Auroras are brilliant ribbons of light weaving across Earth's northern or southern polar regions. These natural light shows are caused by magnetic storms that have been triggered by solar activity, such as solar flares (explosions on the Sun) or coronal mass ejections (ejected gas bubbles). Energetic charged particles from these events are carried from the Sun by the solar wind.", "When these particles seep through Earth's magnetosphere, they cause substorms. Then fast moving particles slam into our thin, high atmosphere, colliding with Earth's oxygen and nitrogen particles. As these air particles shed the energy they picked up from the collision, each atom starts to glow in a different color." ] }, { "url": "https://www.valofinland.com/what-causes-the-colours-in-aurora-borealis/", "title": "What Causes the Colours in Aurora Borealis? - VALO Finland", "snippets": [ "These collisions excite the gas particles, causing them to emit light. The phenomenon typically occurs in the polar regions because the Earth's magnetic field directs the solar wind particles towards the poles." ], "citations": [ "The Aurora Borealis is a result of interactions between solar wind and the Earth's atmosphere. Solar wind is a stream of charged particles released from the sun's upper atmosphere, known as the corona. When these particles reach Earth, they collide with gases in our atmosphere, such as oxygen and nitrogen. These collisions excite the gas particles, causing them to emit light." ] }, { "url": "https://triplefatgoose.com/blogs/down-time/understanding-the-aurora-borealis", "title": "The Aurora Borealis", "snippets": [ "As gasses burn at millions of degrees within the sun, there are huge storms that emit charged particles—such as electrons—through space. Some of these particles fly directly from the sun to Earth." ], "citations": [ "When electrons fly through space, two things can happen: they are reflected away by the Earth's magnetic field, or they follow it to the poles. Because the magnetic field is weaker at the poles, the electrons are able to freely enter the atmosphere without being reflected away." ] } ], "results": [ { "url": "https://www.jpl.nasa.gov/nmp/st5/SCIENCE/aurora.html", "title": "How Auroras Form", "snippets": [ "Auroras are brilliant ribbons of light weaving across Earth's northern or southern polar regions. These natural light shows are caused by magnetic storms that have been triggered by solar activity." ] }, { "url": "https://auroraqueenresort.fi/what-causes-the-northern-lights-to-appear/", "title": "What causes the northern lights to appear? - Aurora Queen Resort", "snippets": [ "The northern lights, also known as aurora borealis, are a mesmerising natural light display that occurs when charged particles from the sun collide with gases in Earth's atmosphere." ] }, { "url": "https://triplefatgoose.com/blogs/down-time/understanding-the-aurora-borealis", "title": "The Aurora Borealis", "snippets": [ "When millions of photons of light are emitted at the same time, it causes the sky to light up and creates the Aurora Borealis." ] } ] } ``` **SDK Code** ```python What causes the aurora borealis import requests url = "https://api.you.com/v1/answer" payload = { "query": "what causes the aurora borealis" } headers = { "X-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript What causes the aurora borealis const url = 'https://api.you.com/v1/answer'; const options = { method: 'POST', headers: {'X-API-Key': '', 'Content-Type': 'application/json'}, body: '{"query":"what causes the aurora borealis"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go What causes the aurora borealis package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.you.com/v1/answer" payload := strings.NewReader("{\n \"query\": \"what causes the aurora borealis\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") 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 What causes the aurora borealis import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.you.com/v1/answer") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"query\": \"what causes the aurora borealis\"\n}") .asString(); ``` ```csharp What causes the aurora borealis using RestSharp; var client = new RestClient("https://api.you.com/v1/answer"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"query\": \"what causes the aurora borealis\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift What causes the aurora borealis import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = ["query": "what causes the aurora borealis"] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.you.com/v1/answer")! 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() ``` ### Current federal funds rate with monthly freshness **Request** ```json { "query": "what is the current federal funds rate", "freshness": "month" } ``` **Response** ```json { "answer": "The current federal funds rate target range is 3.50% to 3.75%, with the effective overnight rate around 3.63–3.64%. [[1, 2, 3]]", "sources": [ { "url": "https://www.usatoday.com/story/money/economy/2026/06/17/fed-rate-decision-meeting-updates--live/90569737007/", "title": "Fed rate decision announced in Warsh's first meeting: Recap", "snippets": [ "The federal funds rate, a benchmark for interest rates across the country, remains at a range of 3.5% to 3.75%." ], "citations": [ "The federal funds rate, a benchmark for interest rates across the country, remains at a range of 3.5% to 3.75%, as it has so far this year and in line with forecasters' expectations for the June meeting." ] }, { "url": "https://www.nerdwallet.com/banking/news/what-is-the-fed-rate", "title": "What Is the Federal Funds Rate? - NerdWallet", "snippets": [ "The federal funds rate — or Fed rate — is the interest rate banks pay one another to borrow or loan money overnight. The current target range is 3.50% to 3.75%." ], "citations": [ "The current target range is 3.50% to 3.75%" ] }, { "url": "https://www.cbsnews.com/news/fed-meeting-fomc-today-kevin-warsh-interest-rates/", "title": "Federal Reserve holds interest rates steady but leaves door open ...", "snippets": [ "The Federal Open Market Committee (FOMC) kept the federal funds rate, which affects borrowing costs for consumers and businesses, in its current range of 3.5% to 3.75%." ], "citations": [ "The current federal funds rate target range is 3.50%-3.75%, set by the FOMC at its March 18-19, 2026 meeting." ] } ], "results": [ { "url": "https://fred.stlouisfed.org/series/FEDFUNDS", "title": "Federal Funds Effective Rate (FEDFUNDS)", "snippets": [ "May 2026: 3.63, Apr 2026: 3.64, Mar 2026: 3.64, Feb 2026: 3.64, Jan 2026: 3.64" ] }, { "url": "https://tradingeconomics.com/united-states/interest-rate", "title": "United States Fed Funds Interest Rate", "snippets": [ "The benchmark interest rate in the United States was last recorded at 3.75 percent." ] }, { "url": "https://fred.stlouisfed.org/series/DFF", "title": "Federal Funds Effective Rate (DFF)", "snippets": [ "2026-06-26: 3.63, 2026-06-25: 3.63, 2026-06-24: 3.63, 2026-06-23: 3.63, 2026-06-22: 3.63" ] } ] } ``` **SDK Code** ```python Current federal funds rate with monthly freshness import requests url = "https://api.you.com/v1/answer" payload = { "query": "what is the current federal funds rate", "freshness": "month" } headers = { "X-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Current federal funds rate with monthly freshness const url = 'https://api.you.com/v1/answer'; const options = { method: 'POST', headers: {'X-API-Key': '', 'Content-Type': 'application/json'}, body: '{"query":"what is the current federal funds rate","freshness":"month"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Current federal funds rate with monthly freshness package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.you.com/v1/answer" payload := strings.NewReader("{\n \"query\": \"what is the current federal funds rate\",\n \"freshness\": \"month\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") 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 Current federal funds rate with monthly freshness import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.you.com/v1/answer") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"query\": \"what is the current federal funds rate\",\n \"freshness\": \"month\"\n}") .asString(); ``` ```csharp Current federal funds rate with monthly freshness using RestSharp; var client = new RestClient("https://api.you.com/v1/answer"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"query\": \"what is the current federal funds rate\",\n \"freshness\": \"month\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Current federal funds rate with monthly freshness import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "query": "what is the current federal funds rate", "freshness": "month" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.you.com/v1/answer")! 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() ``` ### Top local news in the UK **Request** ```json { "query": "top local news today", "country": "GB", "language": "EN" } ``` **Response** ```json { "answer": "Today's top local news from Leicestershire Live includes a police chase on the A46 that ended in a serious collision and a stolen van crash into a BMW, a multi-vehicle crash on the M1 causing injuries, a major road closure after a serious collision, an investigation finding higher baby death rates at city hospitals, concerns over the Cultural Quarter's future, and a fresh bid to demolish a local shopping centre. Additionally, 16 Leicester City players are set to leave with two transfers already confirmed, and an Indian restaurant that survived a fire is now thriving after seven years. [[1]]", "sources": [ { "url": "https://www.leicestermercury.co.uk/", "title": "Leicestershire Live - Latest local news, sport & business from ...", "snippets": [ "Man charged and named after A46 police chase leads to serious collision. More babies die at city hospitals than comparable trusts, investigation finds." ], "citations": [ "Stolen van in police chase crashed into BMW in A46 horror crash", "Man charged and named after A46 police chase leads to serious collision", "Two men injured after serious multi-vehicle Leicestershire M1 crash", "16 players leaving Leicester City today as two transfers already confirmed and contract awaiting" ] } ], "results": [ { "url": "https://www.leicestermercury.co.uk/", "title": "Leicestershire Live - Latest local news, sport & business from ...", "snippets": [ "Man charged and named after A46 police chase leads to serious collision. Two men injured after serious multi-vehicle Leicestershire M1 crash." ] }, { "url": "https://www.mylondon.news/", "title": "MyLondon - The latest London news, sport, entertainment and more", "snippets": [ "A4 Cranford closure live as police incident closes road near Heathrow Airport. Second London heatwave timeline and how high temperatures will rise." ] }, { "url": "https://www.glasgowtimes.co.uk/", "title": "Glasgow News, Sport, Events", "snippets": [ "Protesters unveil cardboard bus at rally over transport fares and reliability. Police issue update two days after teen girl raped in Glasgow park." ] } ] } ``` **SDK Code** ```python Top local news in the UK import requests url = "https://api.you.com/v1/answer" payload = { "query": "top local news today", "country": "GB", "language": "EN" } headers = { "X-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Top local news in the UK const url = 'https://api.you.com/v1/answer'; const options = { method: 'POST', headers: {'X-API-Key': '', 'Content-Type': 'application/json'}, body: '{"query":"top local news today","country":"GB","language":"EN"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Top local news in the UK package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.you.com/v1/answer" payload := strings.NewReader("{\n \"query\": \"top local news today\",\n \"country\": \"GB\",\n \"language\": \"EN\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") 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 Top local news in the UK import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.you.com/v1/answer") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"query\": \"top local news today\",\n \"country\": \"GB\",\n \"language\": \"EN\"\n}") .asString(); ``` ```csharp Top local news in the UK using RestSharp; var client = new RestClient("https://api.you.com/v1/answer"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"query\": \"top local news today\",\n \"country\": \"GB\",\n \"language\": \"EN\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Top local news in the UK import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "query": "top local news today", "country": "GB", "language": "EN" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.you.com/v1/answer")! 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() ```