> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Thin-Viz: Create Card

> Create an embeddable card directly from component configurations

## Notes

* To authenticate, you'll need a [Tako API key](https://tako.com/console/api-keys). 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](/documentation/integrating-tako/chart-creation/overview) 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`.


## OpenAPI

````yaml POST /v1/thin_viz/create/
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /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
        '402':
          description: >-
            Payment required. A PAYG API-credit balance is empty (error_type,
            error_message, balance_cents), or the account has no subscription
            credits left (error, message, upgrade_url).
          content:
            application/json:
              schema:
                properties:
                  error_type:
                    type: string
                  error_message:
                    type: string
                  balance_cents:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
                  upgrade_url:
                    type: string
                type: object
        '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:
    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
              minimum: 100
            - 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
              minimum: 1
            - 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.
    ThinVizCard:
      properties:
        card_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Id
          description: Public ID of the created card.
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Card title.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Card description.
        webpage_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webpage Url
          description: Hosted page URL for the card.
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
          description: Static preview image URL for the card.
        embed_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Embed Url
          description: Embeddable URL for the card.
        card_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Type
          description: The card's chart type (for example, 'bar').
        visualization_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Visualization Data
          description: Inline chart config + data for rendering the card.
          examples:
            - data:
                - x: '2013'
                  'y': 10000
              viz_config:
                title: Revenue
        embed_mode:
          anyOf:
            - type: string
              enum:
                - post
                - postmessage
            - type: 'null'
          title: Embed Mode
          description: >-
            How Tako delivers the embed: 'postmessage' for postMessage embeds,
            and 'post' otherwise.
      type: object
      title: ThinVizCard
      description: >-
        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.
    ComponentConfig:
      properties:
        component_type:
          $ref: '#/components/schemas/ComponentTypeEnum'
          description: >-
            Component type:

            - bubble: Bubble chart (scatter plot with size dimension for
            3-variable data)

            - categorical_bar: Bar chart with categorical x-axis (for example,
            regions or products)

            - choropleth: Choropleth map showing geographic data with color
            intensity by region (US states or world)

            - data_table_chart: Bar chart with auto-generated data table below
            showing values

            - financial_boxes: Financial metric boxes with values and growth
            indicators (for example, Revenue or EPS)

            - generic_timeseries: timeseries chart

            - header: Card header with title and description, automatically
            styled with theme

            - heatmap: 2D heatmap with color intensity representing values (for
            example, a correlation matrix)

            - histogram: Histogram chart showing frequency distribution of
            values

            - person_card: Person profile card from an Exa person search result
            (includes career, education, and about tabs)

            - pie: Pie chart showing proportional data as slices of a circle

            - scatter: Scatter plot showing relationships between two continuous
            variables

            - table: Data table with configurable columns and rows

            - boxplot: Box plot showing statistical distributions (min, Q1,
            median, Q3, max)

            - treemap: Treemap chart showing hierarchical data as proportional
            rectangles

            - waterfall: Waterfall chart showing incremental positive and
            negative changes (for example, an income statement breakdown)
        component_variant:
          anyOf:
            - type: string
            - type: 'null'
          title: Component Variant
          description: Component variant (for example, 'simple' or 'financial').
        config:
          additionalProperties: true
          type: object
          title: Config
          description: Component configuration data
      type: object
      required:
        - component_type
        - config
      title: ComponentConfig
      description: Configuration for a single component in a card.
    ComponentTypeEnum:
      type: string
      enum:
        - categorical_bar
        - choropleth
        - data_table_chart
        - financial_boxes
        - generic_timeseries
        - header
        - heatmap
        - histogram
        - marimekko
        - pie
        - scatter
        - table
        - boxplot
        - treemap
        - waterfall
        - sankey
        - bubble
        - person_card
        - timeline
        - top_level_metric
      title: ComponentTypeEnum
      description: >-
        Component types supported for thin viz schemas with builder support.


        These component types have dedicated builders that process
        configurations,

        add defaults, and apply theme styling automatically.
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````