openapi: 3.1.0
info:
title: Knowledge Search agent tako API
version: 1.0.0
servers:
- url: https://tako.com/api/
description: Tako Production API Server
tags:
- name: tako
paths:
/v3/search:
post:
tags:
- tako
summary: Search
description: Fast-pipeline knowledge search. Returns Tako cards (and web results when requested) with no LLM synthesis.
operationId: search
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Fast-pipeline search results (Tako cards + web results)
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Invalid request data (validation or malformed body).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'408':
description: The request exceeded the processing time limit.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
security:
- apiKey: []
/v1/answer:
post:
tags:
- tako
summary: Answer
description: Fast-pipeline retrieval plus an LLM-synthesized answer with confidence. Replaces the grounding endpoint.
operationId: answer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Synthesized answer grounded in Tako results, web results, or both
content:
application/json:
schema:
$ref: '#/components/schemas/AnswerResponse'
'400':
description: Invalid request data (validation or malformed body).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'408':
description: The request exceeded the processing time limit.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
security:
- apiKey: []
/beta/graph/search:
get:
tags:
- tako
summary: Search the data graph
description: 'Resolve a metric or entity in Tako''s data graph by name. Use this to discover and confirm what data exists before you query. For example, resolve the metric and the entity here, then ask /v3/search or /v1/answer for that entity + metric combination. Public and unauthenticated. Note: Tako does not yet filter results to the production-ready inventory. A returned metric or entity without a production fact table can 404 when you pass it to /beta/graph/related. Pass label to prefer a NER label (a ranking boost, not a filter); by default Tako infers the label from q.'
operationId: graphSearch
parameters:
- description: Search text (min 2 chars).
required: true
schema:
type: string
name: q
in: query
- description: 'Comma-separated facets: metric,entity.'
required: false
schema:
type: string
name: types
in: query
- description: Max results (default 20, max 50).
required: false
schema:
type: integer
name: limit
in: query
- description: Prefer results with this NER label (boost, not a filter — matching nodes rank higher; others still return). Supplying label disables inference.
required: false
schema:
type: string
enum:
- PERSON
- ORG
- GPE
- LOC
- PRODUCT
- EVENT
- LANGUAGE
- MONEY
- METRIC
- STOCK_TICKER
- WEBSITE
name: label
in: query
- description: When true, Tako NER infers the label and grounded-node boosts from q. Set false to disable. Tako ignores this parameter when you supply label. Default true.
required: false
schema:
type: boolean
name: infer_label
in: query
responses:
'200':
description: Matching metrics and entities
content:
application/json:
schema:
$ref: '#/components/schemas/GraphSearchResponse'
'400':
description: Invalid request data (validation or malformed body).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'503':
description: A backing data store is temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
/beta/graph/related:
get:
tags:
- tako
summary: Get a graph node's related nodes
description: 'Explore what a node connects to. The overview returns an ordered `relations` list: named relationships (for example `rel:competes_with`, `rel:in_industry`) first, then a node''s metrics and entities, then similar nodes and membership (part_of, members). The metrics and entities are the entity + metric combinations Tako covers — query /v3/search or /v1/answer for one. Each group carries a stable `key`. Pass `relation`=<key> plus cursor to paginate that one group. Pass the optional q to narrow by a case-insensitive substring on names and aliases (for example, the metrics of an entity that match ''gdp''). Public and unauthenticated.'
operationId: graphRelated
parameters:
- description: Opaque public id of the node.
required: true
schema:
type: string
name: node_id
in: query
- description: Relation key to paginate, for example `rel:competes_with`, `metrics`, `entities`, `siblings`, or `members`.
required: false
schema:
type: string
name: relation
in: query
- description: 'Deprecated: use `relation`. A legacy facet name (metric, entity, sibling, or member) that maps to a key.'
required: false
deprecated: true
schema:
type: string
name: relation_type
in: query
- description: Optional case-insensitive substring filter on the related nodes' names and aliases. It filters every group of the overview, or the single paginated group when you set `relation`.
required: false
schema:
type: string
name: q
in: query
- description: Opaque pagination cursor.
required: false
schema:
type: string
name: cursor
in: query
- description: Page size (default 50, max 100).
required: false
schema:
type: integer
name: limit
in: query
- description: 'Prefer related nodes with this NER label. This is a boost, not a filter: matching nodes rank higher within each relation, and totals do not change. Supplying label disables inference.'
required: false
schema:
type: string
enum:
- PERSON
- ORG
- GPE
- LOC
- PRODUCT
- EVENT
- LANGUAGE
- MONEY
- METRIC
- STOCK_TICKER
- WEBSITE
name: label
in: query
- description: When true, Tako NER infers the label and grounded-node boosts from q. Set false to disable. Tako ignores this parameter when you supply label. It applies only when q is present. Default true.
required: false
schema:
type: boolean
name: infer_label
in: query
responses:
'200':
description: A node's details plus related nodes by facet
content:
application/json:
schema:
$ref: '#/components/schemas/GraphRelatedResponse'
'400':
description: Invalid request data (validation or malformed body).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'404':
description: The requested resource does not exist or has no exportable data.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'503':
description: A backing data store is temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
/beta/graph/node/{id}:
get:
tags:
- tako
summary: Get a graph node by id
description: Resolve a single node by its opaque public id. Search cards, /beta/graph/search, and /beta/graph/related return these ids. Returns the node's name, type, aliases, and description. Public and unauthenticated.
operationId: graphNode
parameters:
- description: Opaque public id of the node.
required: true
schema:
type: string
name: id
in: path
responses:
'200':
description: A single graph node
content:
application/json:
schema:
$ref: '#/components/schemas/GraphNode'
'404':
description: The requested resource does not exist or has no exportable data.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'503':
description: A backing data store is temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
/v1/contents:
post:
tags:
- tako
summary: Download content
description: 'Download the content behind a search result: a CSV of a Tako card''s underlying data, or the full text of a web page. Returns a short-lived presigned download URL. Protected-source cards (data export not available) return 403. Send `quote_only: true` to get only the export''s price (`cost` + `export_pricing`) with an empty payload. A quote is free: Tako fetches nothing and charges nothing.'
operationId: contents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContentsRequest'
responses:
'200':
description: '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.'
content:
application/json:
schema:
$ref: '#/components/schemas/ContentsResponse'
'400':
description: Invalid request data (validation or malformed body).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'403':
description: Action not permitted for this resource (for example, a protected-source export).
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
'404':
description: The requested resource does not exist or has no exportable data.
content:
application/json:
schema:
$ref: '#/components/schemas/BaseAPIError'
security:
- apiKey: []
/v1/thin_viz/create/:
post:
tags:
- tako
description: 'Create a visualization card directly from component configurations. Supported component types: header, generic_timeseries, categorical_bar, stock_boxes, financial_boxes, table.'
operationId: createCard
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCardRequest'
responses:
'200':
description: Card created successfully from schema
content:
application/json:
schema:
$ref: '#/components/schemas/ThinVizCard'
'400':
description: Bad request - validation error or component mismatch
content:
application/json:
schema:
properties:
error:
type: string
type: object
required:
- error
'404':
description: Schema not found
content:
application/json:
schema:
properties:
error:
type: string
type: object
required:
- error
'500':
description: Internal server error
content:
application/json:
schema:
properties:
error:
type: string
type: object
required:
- error
security:
- apiKey: []
components:
schemas:
KnowledgeCardMethodology:
properties:
methodology_name:
anyOf:
- type: string
- type: 'null'
title: Methodology Name
description: The name of the methodology
examples:
- Where the Data Comes From - S&P Global
methodology_description:
anyOf:
- type: string
- type: 'null'
title: Methodology Description
description: 'A concise, one-sentence summary of the methodology: the source and what it measures. When no concise summary is available, this carries the full methodology text.'
examples:
- Financial metrics standardized by S&P Global from company regulatory filings, press releases, and restatements.
type: object
required:
- methodology_name
- methodology_description
title: KnowledgeCardMethodology
ContentsFormat:
type: string
enum:
- csv
- json_records
- json_compact
title: ContentsFormat
description: 'Serialization of tabular (Tako card) data. Web content is always raw text
and carries no content format (content_format is null).'
WebResult:
properties:
title:
type: string
title: Title
description: Title of the web page.
url:
type: string
title: Url
description: URL of the web page.
snippet:
anyOf:
- type: string
- type: 'null'
title: Snippet
description: Excerpt(s) from the page that matched the query.
source_name:
anyOf:
- type: string
- type: 'null'
title: Source Name
description: Publisher or domain name, when Tako can extract it from the URL.
publish_date:
anyOf:
- type: string
- type: 'null'
title: Publish Date
description: Publication date of the page, when available.
content:
anyOf:
- $ref: '#/components/schemas/ResultContent'
- type: 'null'
description: Downloadable content descriptor for this result, fetched via the Contents endpoint. Web results are always downloadable as text. None for callers that do not populate it.
citation_number:
anyOf:
- type: integer
- type: 'null'
title: Citation Number
description: 1-based citation number that the answer's inline [N] markers reference. Set only when the answer inline-cites this result (the Agent API); None on raw-retrieval surfaces.
type: object
required:
- title
- url
title: WebResult
description: 'A single raw web search result from the WEB source index.
Distinct from `KnowledgeCardSource` (a citation inside a synthesized
answer) and `KnowledgeCard` (a Tako visualization). Web results are
raw retrieval output — title, URL, optional snippet. They do not depend
on any LLM synthesis that may also happen over them.'
DataSourceSettings:
properties:
count:
type: integer
maximum: 20.0
minimum: 1.0
title: Count
description: Maximum number of results to return for this source. 1-20.
default: 5
include_contents:
type: boolean
title: Include Contents
description: Inline this source's underlying data directly in the response. For the Tako data source, that is serialized card data (see content_format). For web results, that is the extracted text.
default: false
mode:
$ref: '#/components/schemas/ContentsDeliveryMode'
description: Delivery for inlined card data when include_contents is true. For Tako cards, include_contents always returns a small free inline preview of the most-recent rows in the response body. This field therefore has no effect on Tako cards; it stays for schema stability. total_rows and truncated on the returned content indicate when more data is available. For the full, priced export, call POST /api/v1/contents, which supports mode='url' for a presigned download link.
default: inline
content_format:
$ref: '#/components/schemas/ContentsFormat'
description: 'Serialization for card data: ''json_compact'' (default), ''json_records'', or ''csv''.'
default: json_compact
node_ids:
items:
type: string
type: array
maxItems: 20
title: Node Ids
description: 'Graph node ids to pin into the search; the /beta/graph endpoints return these ids. Pinned nodes always become retrieval candidates and get a strong boost; organic results do not change. Ids are not durable across knowledge-graph rebuilds: the search skips an id that no longer resolves (in strict mode it simply cannot match). Malformed ids fail the request with a 400. Max 20.'
strict:
type: boolean
title: Strict
description: When true, return only data cards that match at least one node in node_ids (which must then be non-empty). When false (the default), pinned nodes rank first but organic results still return. Web results do not change either way.
default: false
additionalProperties: false
type: object
title: DataSourceSettings
description: 'Tako data (card) source settings. It adds the two contents-export
fields on top of the base count and include_contents. Web sources use the
base SourceSettings: Tako always inlines web content as raw text, so web
carries neither field.'
CreateCardRequest:
properties:
components:
items:
$ref: '#/components/schemas/ComponentConfig'
type: array
title: Components
description: Full component configurations
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Card title (falls back to header component title)
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: Card description
source:
anyOf:
- type: string
- type: 'null'
title: Source
description: Data source attribution (displayed in footer)
height:
anyOf:
- type: integer
maximum: 2000.0
minimum: 100.0
- type: 'null'
title: Height
description: Chart height in pixels. When set, overrides the default aspect-ratio-based height for all chart components in this card. Must be between 100 and 2000.
postmessage_embed:
type: boolean
title: Postmessage Embed
description: When True, the embed iframe operates in postMessage mode. The parent page injects visualization_data via window.postMessage after the iframe loads; the embed URL carries no inline data. The response includes embed_mode='postmessage' when this is True, and embed_mode='post' otherwise.
default: false
normalize_currencies:
anyOf:
- type: string
- type: 'null'
title: Normalize Currencies
description: Target ISO 4217 currency code (for example, 'USD' or 'EUR'). When set, Tako converts datasets with recognized currency units to this currency with historical exchange rates. Tako also adds a methodology section that explains the conversion.
image_ttl_minutes:
anyOf:
- type: integer
maximum: 1440.0
minimum: 1.0
- type: 'null'
title: Image Ttl Minutes
description: Minutes to keep the preview image available for download (zero-data-retention (ZDR) cards only). Min 1, max 1440 (24 hours). When set on a ZDR card, Tako generates a temporary preview image and keeps it available for download until the TTL expires. Non-ZDR cards ignore this field.
type: object
required:
- components
title: CreateCardRequest
description: Request model for creating a card directly with components.
AnswerResponse:
properties:
answer:
type: string
title: Answer
description: Synthesized text answer.
cards:
items:
$ref: '#/components/schemas/TakoCard'
type: array
title: Cards
description: Tako cards backing the answer; cards[0] is the lead card — the best one to show alongside the answer.
web_results:
items:
$ref: '#/components/schemas/WebResult'
type: array
title: Web Results
request_id:
type: string
title: Request Id
usage:
anyOf:
- $ref: '#/components/schemas/Usage'
- type: 'null'
type: object
required:
- answer
- request_id
title: AnswerResponse
description: 'Response for POST /api/v1/answer: the synthesized answer plus the
retrieval behind it.'
ExportPricing:
properties:
baseline_usd:
type: number
title: Baseline Usd
description: Flat USD charged once per card export, independent of row count.
row_cpm_usd:
type: number
title: Row Cpm Usd
description: USD charged per 1,000 rows on rows beyond the free allowance (free_rows). Card-level total across the card's priced sources; no per-source breakdown.
free_rows:
type: integer
title: Free Rows
description: Rows included at the baseline price before the per-1,000-row rate (row_cpm_usd) begins to apply.
max_rows_ceiling:
type: integer
title: Max Rows Ceiling
description: Hard cap on rows a single export can return and bill; a larger requested max_rows is clamped to this.
type: object
required:
- baseline_usd
- row_cpm_usd
- free_rows
- max_rows_ceiling
title: ExportPricing
description: 'Card-CSV export pricing RATE, published so a caller can compute an export''s
cost before fetching. Full charge =
baseline_usd + row_cpm_usd * max(0, rows - free_rows) / 1000, rows <= max_rows_ceiling.
row_cpm_usd is the card-level total (sum of the card''s distinct priced sources''
per-1,000-row rate); no per-source breakdown.'
SourceSettings:
properties:
count:
type: integer
maximum: 20.0
minimum: 1.0
title: Count
description: Maximum number of results to return for this source. 1-20.
default: 5
include_contents:
type: boolean
title: Include Contents
description: Inline this source's underlying data directly in the response. For the Tako data source, that is serialized card data (see content_format). For web results, that is the extracted text.
default: false
additionalProperties: false
type: object
title: SourceSettings
GraphNodeType:
type: string
enum:
- metric
- entity
title: GraphNodeType
TakoDatasetColumn:
properties:
name:
type: string
title: Name
description: Column name.
type:
$ref: '#/components/schemas/TakoDatasetColumnType'
description: 'Logical column type: ''string'', ''number'', ''boolean'', ''date'', or ''datetime''. Temporal cells are ISO-8601 strings.'
type: object
required:
- name
- type
title: TakoDatasetColumn
description: Typed header entry; `type` is the JSON-facing column type.
ContentsRequest:
properties:
url:
type: string
title: Url
description: 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.
examples:
- https://tako.com/card/abc123
mode:
$ref: '#/components/schemas/ContentsDeliveryMode'
description: '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.'
default: url
content_format:
$ref: '#/components/schemas/ContentsFormat'
description: 'Serialization for Tako card data: ''csv'' (default), ''json_records'', or ''json_compact''. Ignored for web URLs (always text).'
default: csv
max_rows:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Max Rows
description: Optional cap on the rows returned for a Tako card CSV export. When omitted, it defaults to the free-row allowance (20 rows), 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. Billing counts the rows actually returned. Web URLs ignore this field.
examples:
- 100
quote_only:
type: boolean
title: Quote Only
description: 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. `max_rows` shapes the quote and defaults to the 20-row free allowance, as a real export does. The request ignores `mode` and `content_format`. The same export-safe gate applies, so an unexportable card still returns 403.
default: false
type: object
required:
- url
title: ContentsRequest
description: '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, or json_compact); web URLs ignore it (always
text).'
GraphSearchResponse:
properties:
results:
items:
$ref: '#/components/schemas/GraphNode'
type: array
title: Results
inferred_labels:
anyOf:
- items:
$ref: '#/components/schemas/NerLabel'
type: array
- type: 'null'
title: Inferred Labels
description: Labels that Tako NER inferred from `q` when infer_label ran (boost applied). An empty list means inference ran and found nothing. The field is absent when you supplied an explicit `label`, when infer_label=false, or when there was no q.
type: object
required:
- results
title: GraphSearchResponse
GraphRelationPage:
properties:
key:
type: string
title: Key
description: The relation key of this page.
kind:
$ref: '#/components/schemas/RelationKind'
label:
type: string
title: Label
description: Human-readable group label.
items:
items:
$ref: '#/components/schemas/GraphNode'
type: array
title: Items
total:
type: integer
title: Total
total_capped:
type: boolean
title: Total Capped
description: True when `total` hit the server-side fetch cap; the true count is at least `total`. Pagination ends at the cap — narrow with `q` to reach the tail.
default: false
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
type: object
required:
- key
- kind
- label
- items
- total
title: GraphRelationPage
SearchEffortLevel:
type: string
enum:
- fast
- instant
- deep
title: SearchEffortLevel
description: 'Public effort taxonomy for search and answer. FAST is the default.
INSTANT serves cached embeds without a new data retrieval and works in
all environments. DEEP widens Tako retrieval and adds an LLM rerank for
higher-quality results; it is slower and bills at a premium tier.'
RelationKind:
type: string
enum:
- related
- data
- sibling
- membership
title: RelationKind
description: How Tako derived a relation group.
UsageData:
properties:
cost_usd:
type: number
title: Cost Usd
description: USD cost of the inline data delivered in the response.
datasets:
type: integer
title: Datasets
description: Number of billed data units (datasets) included in the response.
type: object
required:
- cost_usd
- datasets
title: UsageData
description: 'The cost and quantity of inline data delivered in the response: the
agent per-dataset surcharge, the search and answer include_contents
charge, or the contents per-item cost. `datasets` is the count of billed
data units. Absent when the surface did not or cannot emit inline data
(for example, the answer agent).'
TakoCardSource:
properties:
source_name:
anyOf:
- type: string
- type: 'null'
title: Source Name
description: The name of the source
examples:
- S&P Global
- The World Bank
source_description:
anyOf:
- type: string
- type: 'null'
title: Source Description
description: The description of the source
source_index:
$ref: '#/components/schemas/TakoSourceIndex'
description: The index of the source
examples:
- data
- web
url:
anyOf:
- type: string
- type: 'null'
title: Url
description: The URL of the source
examples:
- https://xignite.com
source_text:
anyOf:
- type: string
- type: 'null'
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tako/refs/heads/main/openapi/tako-tako-api-openapi.yml