Tako tako API

openapi: 3.2.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:
    ResultContent:
      properties:
        content_format:
          anyOf:
          - $ref: '#/components/schemas/ContentsFormat'
          - type: 'null'
          description: 'Serialization of the returned card data: ''csv'', ''json_records'', or ''json_compact''. Null for web text (always returned as raw text) and for a quote-only response (nothing was serialized).'
        cost:
          type: number
          title: Cost
          description: Price of this item in USD. On a /contents response this is the amount actually billed; on a quote_only response or a search/answer downloadable card it is a prospective /contents export price (nothing was fetched or billed). Pair with export_pricing to compute a larger export's cost before fetching.
          default: 0.0
        data:
          anyOf:
          - type: string
          - type: 'null'
          title: Data
          description: 'Inline payload as text: card data serialized to CSV, or a web page''s extracted text. Set only for the ''csv'' card format and for web text; null otherwise.'
        records:
          anyOf:
          - items:
              additionalProperties:
                anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                - type: 'null'
              type: object
            type: array
          - type: 'null'
          title: Records
          description: 'Inline card data as verbose JSON: a list of row objects keyed by column name. Set only when content_format is ''json_records''.'
        dataset:
          anyOf:
          - $ref: '#/components/schemas/TakoDataset'
          - type: 'null'
          description: Inline card data as a compact TakoDataset (typed column headers plus positional row arrays). Set only when content_format is 'json_compact'.
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: Presigned download URL for the content, returned in 'url' delivery mode. Null for inline delivery and for quotes; pair with expires_at.
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: ISO-8601 timestamp after which the presigned url stops working. Null whenever url is null.
        total_rows:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Rows
          description: True total number of rows in the card's data, independent of how many rows were returned. Compare with truncated to tell whether more rows are available via a larger max_rows. Null for web text.
        truncated:
          type: boolean
          title: Truncated
          description: True when the returned rows were capped (by the request's max_rows or the 2,000-row system ceiling) and total_rows exceeds the number returned.
          default: false
        export_pricing:
          anyOf:
          - $ref: '#/components/schemas/ExportPricing'
          - type: 'null'
          description: Rate card for a downloadable card CSV, so a caller can compute a full export's cost before fetching. Null for web text and other non-downloadable content.
      type: object
      title: ResultContent
      description: 'Describes the downloadable content behind a result.


        Pricing: for a Tako card CSV export, the charge is a flat per-export

        baseline plus a per-source, per-row CPM on the rows returned beyond the

        free-row allowance. Web text bills at the standard Contents rate.


        The meaning of `cost` depends on the surface. On `/contents` responses,

        `cost` is the actual charge, and it reconciles with what that response

        billed. The exception is a `quote_only` response, where `cost` is a

        prospective price: Tako neither fetched nor billed the export, and the

        payload and url fields are null. On search and answer downloadable

        cards, `cost` is a prospective `/contents` quote (the per-export

        baseline floor), not what this response billed. On a metered

        `include_contents` request, the per-card `cost` therefore diverges from

        `usage.total_cost_usd` (the inline preview bills about $0), and the sum

        of per-card `cost` will not reconcile with `usage`. Treat `cost` plus

        `export_pricing` as the price of a `/contents` export of this card.


        `export_pricing` carries the rate so that a caller can compute the full

        charge before fetching: baseline_usd + row_cpm_usd * max(0, rows -

        free_rows) / 1000, with rows <= max_rows_ceiling. `export_pricing` is

        null for web text and non-downloadable content.


        Tako populates exactly one payload group once it delivers contents:

        `data` (CSV or web text), `records` (verbose JSON), `dataset` (compact

        TakoDataset), or `url` plus `expires_at` (presigned download).

        `content_format` names the serialization; it is null for web text and

        for an undelivered quote. When every payload field is unset, this is

        just the quote (`cost`); fetch the content later via the Contents

        endpoint.'
    RelationKind:
      type: string
      enum:
      - related
      - data
      - sibling
      - membership
      title: RelationKind
      description: How Tako derived a relation group.
    TakoDatasetColumnType:
      type: string
      enum:
      - string
      - number
      - boolean
      - date
      - datetime
      title: TakoDatasetColumnType
      description: 'Logical column type declared in a TakoDataset header. Temporal cells

        are ISO-8601 strings. Each column declares ''date'' or ''datetime'' on its

        own: a temporal column whose non-null values are all timezone-naive

        midnights declares ''date''.'
    BaseAPIError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
      type: object
      required:
      - error_message
      - error_type
      title: BaseAPIError
    OutputSettings:
      properties:
        image_dark_mode:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Image Dark Mode
          description: Whether to render card preview images in dark mode.
        force_refresh:
          type: boolean
          title: Force Refresh
          description: 'Instant mode only, and currently informational: on these endpoints, instant (effort=''instant'') always operates in build-and-refresh mode regardless of this flag. Instant retrieves data for embeds that are missing or stale, then creates or refreshes their static embeds. Embeds that are already fresh (within the refresh cadence) return as-is; Tako does not re-retrieve them. Identical queries therefore reuse the same content-addressed embed and return a stable embed URL.'
          default: false
      additionalProperties: false
      type: object
      title: OutputSettings
    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.
    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
    ContentsDeliveryMode:
      type: string
      enum:
      - url
      - inline
      title: ContentsDeliveryMode
      description: 'How contents reach the caller. URL returns a short-lived presigned file

        download; INLINE returns the content in the response body.'
    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.'
    ContentsResponse:
      properties:
        contents:
          items:
            $ref: '#/components/schemas/ContentItem'
          type: array
          title: Contents
          description: Downloadable artifacts for the requested URL.
        request_id:
          type: string
          title: Request Id
          description: Unique identifier for this request.
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
      type: object
      required:
      - request_id
      title: ContentsResponse
      description: '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.'
    TakoDataset:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/TakoDatasetColumn'
          type: array
          title: Columns
          description: Ordered column headers (name + type), one per position in every row.
        rows:
          items:
            items:
              anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
              - type: 'null'
            type: array
          type: array
          title: Rows
          description: Row data as positional cell arrays aligned to `columns` order. Cells are string/number/boolean/null; nulls are preserved, never coerced.
        total_rows:
          type: integer
          title: Total Rows
          description: True total number of rows in the underlying data, before any truncation.
        truncated:
          type: boolean
          title: Truncated
          description: True when `rows` was capped and total_rows exceeds the number returned.
        ref:
          type: string
          title: Ref
          description: Source URL the dataset was derived from (e.g. the Tako card URL).
        sources:
          items:
            $ref: '#/components/schemas/TakoDatasetSource'
          type: array
          title: Sources
          description: 'Provenance for the dataset: the sources the rows were drawn from.'
        provenance:
          type: string
          enum:
          - query
          - web_extraction
          title: Provenance
          description: 'How the rows were produced: ''query'' (Tako data) or ''web_extraction''.'
          default: query
      type: object
      required:
      - columns
      - rows
      - total_rows
      - truncated
      - ref
      - sources
      title: TakoDataset
      description: 'The dataset-slot envelope: exact retrieved rows as positional arrays

        in `columns` order. The rows come directly from the data source; the LLM

        never transcribes them.'
    MetricDefinition:
      properties:
        name:
          type: string
          title: Name
          description: The metric's display name
          examples:
          - Gross Domestic Product (current US$)
        definition:
          type: string
          title: Definition
          description: Human-readable definition of the metric
      type: object
      required:
      - name
      - definition
      title: MetricDefinition
      description: 'Definition of a metric shown on a card. Sourced from the metric''s

        ValueType definition — the same text as the in-app methodology ''Metrics''

        tab.'
    SearchResponse:
      properties:
        cards:
          items:
            $ref: '#/components/schemas/TakoCard'
          type: array
          title: Cards
        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:
      - request_id
      title: SearchResponse
    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.'
    ContentItem:
      properties:
        content_format:
          anyOf:
          - $ref: '#/components/schemas/ContentsFormat'
          - type: 'null'
          description: 'Serialization of the returned card data: ''csv'', ''json_records'', or ''json_compact''. Null for web text (always returned as raw text) and for a quote-only response (nothing was serialized).'
        cost:
          type: number
          title: Cost
          description: Price of this item in USD. On a /contents response this is the amount actually billed; on a quote_only response or a search/answer downloadable card it is a prospective /contents export price (nothing was fetched or billed). Pair with export_pricing to compute a larger export's cost before fetching.
          default: 0.0
        data:
          anyOf:
          - type: string
          - type: 'null'
          title: Data
   

# --- 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