> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# For Your Coding Agent

> The build reference for coding agents integrating Tako Answer. Self-contained and copy-paste-ready — endpoint, X-API-Key auth, every request parameter, the grounded answer response shape, and runnable cURL, Python, and TypeScript examples. Use this page to generate a working Answer integration.

This page is a complete, self-contained reference for building against **Tako Answer**. Every example runs after you supply an API key, every parameter is grounded in the live API, and the common mistakes are called out explicitly. For the auto-generated schema, see the [Answer API reference](/api-reference/answer); for a narrative introduction, see the [Overview](/documentation/integrating-tako/answer/overview).

## What Answer does

`POST https://tako.com/api/v1/answer` takes a natural-language `query` and returns a **synthesized written `answer`** in a single fast call, grounded in real-time, trusted data — alongside the **Tako knowledge cards** and **web results** that back it. Use it to ground your own model output and keep what you show consistent with Tako's data (for example, grounding a stock-price analysis with Tako's up-to-date pricing card).

Answer takes the **same request body as [Search](/documentation/integrating-tako/search/for-coding-agent)**; the only response difference is the added `answer` string. Because each backing card ships with named sources and methodology, you get an answer you can **attribute and cite**, not just a paragraph of text.

* **Base URL:** `https://tako.com/api/`
* **Auth:** send your API key in the **`X-API-Key`** request header (not a bearer token). Create a key in the [Tako console](https://tako.com/console/api-keys).

## Install

```bash theme={null}
pip install tako-sdk      # Python
npm install tako-sdk      # TypeScript / JavaScript
```

## Minimal working example

Each snippet makes the same call and is complete after you set `TAKO_API_KEY`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://tako.com/api/v1/answer \
    -H "X-API-Key: $TAKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What is the weather in San Francisco?"
    }'
  ```

  ```python Python theme={null}
  import os
  from tako import Configuration, SearchRequest
  from tako.lib import Tako

  config = Configuration()
  config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
  client = Tako(config)

  response = client.answer(SearchRequest(query="What is the weather in San Francisco?"))
  print(response.answer)
  for card in response.cards or []:
      print(card.title, card.webpage_url)
  ```

  ```typescript TypeScript theme={null}
  import { Tako } from "tako-sdk";

  const tako = new Tako({ apiKey: process.env.TAKO_API_KEY! });

  const response = await tako.answer({ query: "What is the weather in San Francisco?" });
  console.log(response.answer);
  for (const card of response.cards ?? []) {
    console.log(card.title, card.webpage_url);
  }
  ```
</CodeGroup>

## Request parameters

The body is a `SearchRequest` — identical to Search. Only `query` is required; `effort` (`fast` default / `instant` / `deep`), `sources`, `country_code` (`US`), `locale` (`en-US`), `timezone`, and `output_settings` all behave exactly as documented in the [Search reference](/documentation/integrating-tako/search/for-coding-agent#request-parameters).

### Latency

Target p50 latency (not a guarantee), by `effort`:

| `effort`           | Target p50 |
| ------------------ | ---------- |
| `instant`          | \~750 ms   |
| `fast` *(default)* | \~950 ms   |
| `deep`             | \~6 s      |

### Choosing sources

<Tip>
  **Use both sources.** Omit `sources` and Answer grounds in **both** Tako's curated knowledge graph and the live web — the recommended default for the most complete, accurate answer. Narrow to one index only when you have a specific reason.
</Tip>

By default Answer grounds in **both** Tako's curated knowledge graph (`data`) and the live web (`web`), 5 results each. `sources` is an **object** whose keys select the indexes — a source is used only if its key is present:

| `sources` value  | Grounds in                                       |
| ---------------- | ------------------------------------------------ |
| *(omitted)*      | both — equivalent to `{ "data": {}, "web": {} }` |
| `{ "data": {} }` | Tako curated knowledge graph only                |
| `{ "web": {} }`  | the live web only                                |

Per-source `count` (1–20, default 5), `include_contents`, and `defer_data_retrieval` (data only; mutually exclusive with `include_contents`) work as in Search. The legacy key `tako` maps to `data`.

## What a response looks like

A `200` returns an `AnswerResponse` — a `SearchResponse` plus a required `answer` string. **`cards[0]` is the lead card**: the best one to show alongside the answer.

```json theme={null}
{
  "answer": "It's currently 52°F in San Francisco and feels like 52°F, with partly cloudy skies. Today's high is 54°F and the low is 50°F; the rest of the week is expected to be mostly clear with highs around 53–55°F.",
  "cards": [
    {
      "card_id": "mA-C6b48zxyU3G33JJdO",
      "title": "San Francisco, CA Weather Metrics",
      "description": "This card displays the weather forecast for San Francisco, CA for today. Currently, it's 52°F and feels like 52°F. The high for today is 54°F and the low is 50°F.",
      "webpage_url": "https://tako.com/card/mA-C6b48zxyU3G33JJdO/",
      "image_url": "https://tako.com/api/v1/image/mA-C6b48zxyU3G33JJdO/",
      "embed_url": "https://tako.com/embed/mA-C6b48zxyU3G33JJdO/",
      "sources": [
        {
          "source_name": "NOAA National Weather Service",
          "source_description": "The U.S. agency providing weather forecasts and warnings, part of NOAA.",
          "source_index": "tako"
        }
      ],
      "methodologies": [
        {
          "methodology_name": "Data Collection",
          "methodology_description": "Raw meteorological data from NOAA's NWS, sourced from weather.gov, with no statistical adjustments applied."
        }
      ],
      "source_indexes": ["tako"]
    }
  ],
  "web_results": [],
  "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
}
```

| Field         | Type   | Description                                                                                   |
| ------------- | ------ | --------------------------------------------------------------------------------------------- |
| `answer`      | string | The synthesized, grounded answer. Always present.                                             |
| `cards`       | array  | Backing Tako cards; `cards[0]` is the lead card to display.                                   |
| `web_results` | array  | Backing web results (`title`, `url`, plus optional `snippet`, `source_name`, `publish_date`). |
| `request_id`  | string | Always present — log it for support/debugging.                                                |

Backing cards carry the same `content`/`cost` fields as [Search](/documentation/integrating-tako/search/for-coding-agent#what-a-response-looks-like); credits apply per call — see [Credits & billing](/documentation/additional-resources/credits-and-billing#the-cost-field).

### Grounding and attribution

To keep your content accurate and citable, read these fields off each card:

* **`description`** — a natural-language description of the data and the latest data point.
* **`sources`** — named sources (`source_name`, `source_description`) backing the card.
* **`methodologies`** — how the data was collected or derived.
* **`image_url`** — a static image of the card to display next to the answer.

## When to use Answer

Answer is for a **ready-to-show, source-attributed answer in one call** — synthesized prose that draws the **best answer from both Tako's curated data and the live web**, shipped with the cards and web results that back it. Reach for it when:

* **You want prose you can drop straight in.** One synchronous call returns a written `answer`, not raw results to assemble yourself — ideal for chat assistants and any surface that needs text.
* **The answer has to be citable.** Every answer comes back with its backing cards — named sources and methodology — so you can attribute each claim and keep content auditable.
* **You want it to stay current.** Re-run the same query to refresh prose that stays grounded in live data, across Tako's curated knowledge graph **and** the live web by default.
* **You're grounding your own model.** Inline the underlying data with `include_contents` so your model reasons over real numbers, not snippets.

**Only need the raw cards and web results?** Use [Search](/documentation/integrating-tako/search/for-coding-agent) — the same request body, without the synthesized `answer`. **Need multi-step reasoning** — resolving a cohort, ranking a set, multi-hop aggregation? Use the [Agent](/documentation/integrating-tako/agent/for-coding-agent).

## Common mistakes

<Warning>
  Avoid these — they are the patterns coding agents most often get wrong.
</Warning>

| Wrong                                    | Correct                                                                |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| `Authorization: Bearer $KEY`             | `X-API-Key: $KEY`                                                      |
| Posting to `/v1/search` or `/v3/answer`  | Answer is `POST /v1/answer`; Search is `POST /v3/search`               |
| `"sources": ["data"]` (array)            | `"sources": { "data": {} }` (object — key presence selects the source) |
| Treating any card as the lead            | `cards[0]` is the lead card — display it alongside the `answer`        |
| Showing the `answer` without attribution | Read `sources` / `methodologies` off the backing cards to cite it      |

## Errors

Failures return a `BaseAPIError` body: `{ "error_message": "...", "error_type": "..." }`.

| Status | Meaning                                          | Fix                                                                                                                |
| ------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `400`  | Malformed request (bad JSON, invalid parameter). | Validate the body against the parameters above.                                                                    |
| `401`  | Missing or invalid API key.                      | Send a valid key in the `X-API-Key` header.                                                                        |
| `402`  | Out of credits (insufficient balance).           | Top up credits — see [Credits & billing](/documentation/additional-resources/credits-and-billing#running-out-402). |
| `408`  | The request timed out.                           | Retry the request.                                                                                                 |