Skip to main content
POST
Download content

Notes

  • To authenticate, you’ll need a Tako API key. It’s best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
  • Contents downloads the data behind a result returned by Search or Answer. Pass the result’s URL and Tako returns a short-lived download URL — a CSV of a Tako card’s data, or the extracted text of any other web page.
  • You don’t pass a format; Tako detects the right content from the URL and the response reports what it produced.
A result is downloadable when it carries a content descriptor in the Search or Answer response. Use that result’s URL here — a card’s webpage_url or a web result’s url.

Authorizations

X-API-Key
string
header
required

Body

application/json

Request body for POST /api/v1/contents.

The caller passes the result URL it wants downloadable content for, and the endpoint detects the right content from the URL itself. A Tako card URL resolves to the card's underlying data. Any other URL resolves to the page's extracted full text. mode controls delivery: url (the default) returns a presigned download link, and inline returns the content in the response. content_format selects the card serialization (csv, json_records, json_compact, or card_json); web URLs ignore it (always text).

url
string
required

The result URL to fetch downloadable content for (a TakoCard.webpage_url or a WebResult.url). A Tako card URL yields a CSV of the card's data; any other URL yields the page's extracted text.

Example:

"https://tako.com/card/abc123"

mode
enum<string>
default:url

Delivery mode. 'url' (the default) returns a presigned download link. 'inline' returns the content in the response body: CSV data up to the 2,000-row system ceiling (with total_rows and truncated reported), or web text.

Available options:
url,
inline
content_format
enum<string>
default:csv

Serialization for Tako card data: 'csv' (default), 'json_records', 'json_compact', or 'card_json' (a rich card-type-specific JSON object; not all card types support it). Ignored for web URLs (always text).

Available options:
csv,
json_records,
json_compact,
card_json
max_rows
integer | null

Optional cap on the rows a Tako card export is priced against. When omitted, it defaults to your account's free-row allowance (20 rows on the standard plan), billed at the baseline only. Raise it to export more rows, up to the 2,000-row system ceiling (Tako clamps larger values). Rows beyond the free allowance bill at the per-1,000-row rate. Tako never bills more rows than it returns. Every card format returns the rows up to this cap and bills them, including card_json. Web URLs ignore this field.

Required range: x >= 1
Example:

100

max_chars
integer
default:1000000

Character cap on extracted web page text. Ignored for Tako card URLs (they use max_rows). The default is the full page text, up to the 1000000-character ceiling. To truncate, pass a smaller value.

Required range: 1 <= x <= 1000000
Example:

50000

quote_only
boolean
default:false

When true, return only the price of the export (cost + export_pricing) without fetching content or charging. The response item's payload and url fields are null, and the request is free. One exception: a card_json quote returns 'card_data_schema', the shape the export would deliver. Test 'content_format' for null to tell a quote from a delivery. max_rows shapes the quote and defaults to your account's free-row allowance, as a real export does. The request ignores mode. Every format prices a quote from max_rows, so a quote is instant and makes no call to a data provider. A quote is an upper bound on the charge: an export of a card with fewer rows than the cap bills less. A card_json export is truncated to max_rows like every other format, so the charge can never exceed the quote for the same cap. A card_json quote reports no total_rows, because it does not build the payload. The same export-safe gate applies, so an unexportable card still returns 403, and a card type with no card_json shape still returns 422.

Response

Downloadable content for a result: a presigned URL plus format and cost metadata. For a quote_only request the item instead carries only the price (cost + export_pricing) with all payload and url fields null.

Response for POST /api/v1/contents.

contents is a list so that the contract stays stable if a single result ever yields multiple artifacts. Today it always carries exactly one item.

request_id
string
required

Unique identifier for this request.

contents
ContentItem · object[]

Downloadable artifacts for the requested URL.

usage
Usage · object | null

Usage for one metered request. total_cost_usd is always present (the total quoted charge). compute and data are the additive breakdown; each appears only where it applies. total_cost_usd always equals the sum of the components that appear.