Skip to main content
POST
cURL

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.
  • Creates a card in a single API call with full component configurations. No schema step is required.
  • The response includes embed_url, image_url, and webpage_url for embedding the card.
  • If no title is provided, it falls back to the title from the first header component, or defaults to “Card”.
  • See the Thin-Viz Guide for full examples and available component types.
  • For large datasets (>1MB): Use gzip compression to send payloads up to 10x larger.
  • Preview images for ZDR cards: Set image_ttl_minutes (1–1440) to make a temporary preview image available via image_url. The image can be downloaded on demand with query params (dark_mode, width, height, hideFooter) until the TTL expires, after which the endpoint returns 410 Gone.

Authorizations

X-API-Key
string
header
required

Body

application/json

Request model for creating a card directly with components.

components
ComponentConfig · object[]
required

Full component configurations

title
string | null

Card title (falls back to header component title)

description
string | null

Card description

source
string | null

Data source attribution (displayed in footer)

height
integer | null

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.

Required range: 100 <= x <= 2000
postmessage_embed
boolean
default:false

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.

normalize_currencies
string | null

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
integer | null

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.

Required range: 1 <= x <= 1440

Response

Card created successfully from schema

Response for POST /api/v1/thin_viz/create — a created visualization card.

Distinct from KnowledgeCard: thin_viz builds a self-contained chart from a caller-supplied component schema, so it never carries retrieval provenance (sources, source_indexes) or downloadable raw data. Render the card via embed_url and preview it via image_url. visualization_data carries the inline chart config and data.

This schema documents the populated subset of the response. The wire payload also includes the remaining KnowledgeCard fields (sources, source_indexes, methodologies, data_url, and so on) as null.

card_id
string | null

Public ID of the created card.

title
string | null

Card title.

description
string | null

Card description.

webpage_url
string | null

Hosted page URL for the card.

image_url
string | null

Static preview image URL for the card.

embed_url
string | null

Embeddable URL for the card.

card_type
string | null

The card's chart type (for example, 'bar').

visualization_data
Visualization Data · object | null

Inline chart config + data for rendering the card.

Example:
embed_mode
enum<string> | null

How Tako delivers the embed: 'postmessage' for postMessage embeds, and 'post' otherwise.

Available options:
post,
postmessage