Skip to main content
This is the quick, copy-pasteable reference for building cards with Tako Thin-Viz. For the full example gallery (every component with a worked example), see the Overview; for the auto-generated schema, see the API reference.

​
What Thin-Viz does

POST https://tako.com/api/v1/thin_viz/create/ turns your own data into an interactive, embeddable Tako card. One call, one card: you post an array of components, and the response gives you embed_url, image_url, and webpage_url.
  • 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.

​
Install

pip install tako-sdk      # Python
npm install tako-sdk      # TypeScript / JavaScript

​
Minimal working example

A single line chart. Set TAKO_API_KEY and run. 
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
  -H "X-API-Key: $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Monthly Revenue",
    "source": "Internal Analytics",
    "components": [
      {
        "component_type": "generic_timeseries",
        "config": {
          "datasets": [
            {
              "label": "Revenue",
              "data": [
                {"x": "2024-01", "y": 50000},
                {"x": "2024-02", "y": 62000},
                {"x": "2024-03", "y": 71000}
              ],
              "units": "$"
            }
          ],
          "chart_type": "line",
          "title": "Monthly Revenue"
        }
      }
    ]
  }'

import os
from tako import Configuration, CreateCardRequest, ComponentConfig
from tako.lib import Tako

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

card = client.create_card(CreateCardRequest(
    title="Monthly Revenue",
    source="Internal Analytics",
    components=[
        ComponentConfig(
            component_type="generic_timeseries",
            config={
                "datasets": [
                    {
                        "label": "Revenue",
                        "data": [
                            {"x": "2024-01", "y": 50000},
                            {"x": "2024-02", "y": 62000},
                            {"x": "2024-03", "y": 71000}
                        ],
                        "units": "$"
                    }
                ],
                "chart_type": "line",
                "title": "Monthly Revenue"
            },
        ),
    ],
))
print(card.embed_url)

import { Tako } from "tako-sdk";

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

const card = await tako.createCard({
  title: "Monthly Revenue",
  source: "Internal Analytics",
  components: [
    {
      component_type: "generic_timeseries",
      config: {
        datasets: [
          {
            label: "Revenue",
            data: [
              { x: "2024-01", y: 50000 },
              { x: "2024-02", y: 62000 },
              { x: "2024-03", y: 71000 },
            ],
            units: "$",
          },
        ],
        chart_type: "line",
        title: "Monthly Revenue",
      },
    },
  ],
});
console.log(card.embed_url);
The response is a card with card_id, title, description, embed_url, image_url, webpage_url, and card_type.

​
Request fields (CreateCardRequest)

FieldTypeRequiredDescription
componentsarrayYesOrdered list of components; they render top-to-bottom on the card.
titlestringNoCard title (falls back to a header component’s title, else “Card”).
descriptionstringNoCard description.
sourcestringNoSource attribution shown in the footer.
heightinteger (100–2000)NoOverride the aspect-ratio height.
postmessage_embedbooleanNoEnable postMessage data injection mode (default false).
normalize_currenciesstringNoTarget ISO 4217 code to normalize currency values to.
image_ttl_minutesinteger (1–1440)NoZDR cards only — keep a downloadable preview image for this many minutes, then 410 Gone.
Each entry in components is a ComponentConfig: component_type (from the enum below) + a free-form config object (plus optional component_variant).

​
Component types

These are the valid component_type values (ComponentTypeEnum): header · generic_timeseries · categorical_bar · data_table_chart · financial_boxes · table · timeline · pie · histogram · scatter · bubble · choropleth · heatmap · boxplot · treemap · waterfall · sankey · marimekko · person_card · top_level_metric See the Overview for a worked config example of each.
For stock-style cards, use generic_timeseries with show_kicker_boxes: true (each dataset with a kicker renders a box above the chart). stock_boxes appears in older examples but is not a ComponentTypeEnum value — prefer generic_timeseries + show_kicker_boxes.

​
Data shapes — know which one a component wants

Most components take datasets, but a few take a different shape. Getting this wrong is the most common error:
ShapeComponentsExample
datasets: [{ label, data: [{x, y}], units }]generic_timeseries, categorical_bar, data_table_chart, pie, histogram, treemap{"x": "2024-01", "y": 50000}
datasets with {x, y, r}scatter, bubble (r = radius on bubble){"x": 4.2, "y": 12.5, "r": 15}
Flat data: [{x, y, v}]heatmap, marimekko{"x": "Mon", "y": "AM", "v": 12}
categories: [{ category, values: [] }]boxplotraw values per category
items: []waterfall, financial_boxes{"category": "Revenue", "value": 100, "is_anchor": true}
nodes + linkssankeylinks reference node ids; must form a DAG
columns + rowstabletyped columns (string/number/currency/…)

​
Embedding the card

Drop the returned embed_url into an iframe (add ?dark_mode=true/false to theme it). For full embedding guidance — dynamic resizing, theme matching, glanceable mode — see Embedding Knowledge Cards. 
<iframe src="https://tako.com/embed/CARD_ID" width="600" height="400" frameborder="0"></iframe>

​
Preview images (ZDR cards)

ZDR cards don’t persist visualization data, so they have no standing preview image. Set image_ttl_minutes (1–1440) at creation to get a temporary image_url. Customize it with query params: dark_mode, width, height, hideFooter. After the TTL expires the image endpoint returns 410 Gone. (image_ttl_minutes is ignored for standard cards, which already have persistent images.)

​
Tips & errors

  • Gzip large payloads. For request bodies over ~1 MB, gzip the body (Content-Encoding: gzip) — Thin-Viz accepts it and it compresses well (up to ~10×).
  • Auth: X-API-Key header, not a bearer token.
Errors return a bare { "error": "..." } body:
StatusMeaningFix
400Invalid request (bad component config, unknown component_type, wrong data shape).Check the component_type against the enum and the data shape table above.
404Referenced resource not found.Verify any IDs in the request.
500Server error.Retry; if it persists, contact support.