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

# Import Dashboard

> Create a complete dashboard with charts in a single API call (API key auth)

Single-shot dashboard creation. Accepts a declarative payload describing charts, data source, and layout — returns experiment and facade IDs.

<Note>
  This endpoint uses **API key authentication**. Pass your key via `Authorization: Bearer trvh_sdk_...` or `x-api-key` header.
</Note>

## Request Body

<ParamField body="name" type="string" required>
  Dashboard name displayed in the UI.
</ParamField>

<ParamField body="description" type="string">
  Optional description for the dashboard.
</ParamField>

<ParamField body="dataSource" type="object" required>
  The data source to query against.

  <Expandable title="dataSource properties">
    <ParamField body="dbId" type="string" required>
      Database connection ID (e.g., `D2026A00002`).
    </ParamField>

    <ParamField body="vdmId" type="string">
      Virtual Data Mart ID. When provided, field names are validated against VDM columns.
    </ParamField>

    <ParamField body="connType" type="string" default="VDM">
      Connection type. Use `"VDM"` for Virtual Data Mart sources.
    </ParamField>

    <ParamField body="schemaName" type="string">
      Database schema name (e.g., `"public"`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="charts" type="array">
  Array of chart definitions. Use this for **simple mode** (single section).

  <Expandable title="chart object">
    <ParamField body="title" type="string">
      Display title of the chart.
    </ParamField>

    <ParamField body="type" type="string" required>
      Chart type — friendly name (e.g., `column`, `pie`, `line`, `kpi`) or CH code (e.g., `CH00003`). See [Get Chart Types](/api-reference/get-chart-types) for all options.
    </ParamField>

    <ParamField body="measures" type="array" required>
      Array of measure definitions.

      <Expandable title="measure object">
        <ParamField body="field" type="string" required>
          Column name in the data source.
        </ParamField>

        <ParamField body="aggregation" type="string" default="sum">
          Aggregation function: `sum`, `count`, `average` / `avg`, `min`, `max`, `distinct`, `as-is`.
        </ParamField>
      </Expandable>

      Shorthand: pass a string instead of an object to use the default aggregation (e.g., `"revenue"` is equivalent to `{"field": "revenue", "aggregation": "sum"}`).

      **Using calculations:** To reference a pre-computed calculation (percentage of total, weighted average, etc.) from the VDM, use `"aggregation": "as-is"` with the calculation's label as the `field`. See [Calculations](/calculations#using-calculations-in-sdk-import) for details.
    </ParamField>

    <ParamField body="dimensions" type="array" required>
      Array of dimension field names (strings) or dimension objects.

      <Expandable title="dimension object">
        <ParamField body="field" type="string" required>
          Column name for grouping.
        </ParamField>

        <ParamField body="isDate" type="boolean" default={false}>
          Whether this dimension is a date type.
        </ParamField>
      </Expandable>

      Shorthand: pass a string instead of an object (e.g., `"region"`).
    </ParamField>

    <ParamField body="filters" type="array">
      Array of filter conditions applied to this chart.
    </ParamField>

    <ParamField body="limit" type="number">
      Max number of rows to return. Defaults to `100` if not using `filter`.
    </ParamField>

    <ParamField body="sort" type="array">
      Sort configuration. Each item: `{ "field": "columnName", "direction": "asc" | "desc" }`.
    </ParamField>

    <ParamField body="grid" type="object">
      Chart position and size within the experiment grid. If omitted, auto-generated (KPIs: `width: 3` side-by-side, others: `width: 12` stacked vertically).

      <Expandable title="grid properties">
        <ParamField body="width" type="number">Grid column span (1–12). Default: `12` (full width), `3` for KPI cards.</ParamField>
        <ParamField body="height" type="number">Grid row span. Default: `13`, `6` for KPI cards.</ParamField>
        <ParamField body="x" type="number">Column offset (0-based). Default: `0`.</ParamField>
        <ParamField body="y" type="number">Row offset (0-based). Default: auto-calculated.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="display" type="object">
      Chart visual settings. If omitted, sensible defaults are applied.

      <Expandable title="display properties">
        <ParamField body="showValues" type="boolean" default={true}>Show data values on the chart.</ParamField>
        <ParamField body="showLegend" type="boolean" default={true}>Show chart legend.</ParamField>
        <ParamField body="showTooltip" type="boolean" default={false}>Show hover tooltips.</ParamField>
        <ParamField body="showNull" type="boolean" default={false}>Include null values.</ParamField>
        <ParamField body="enableZoom" type="boolean" default={false}>Enable chart zoom.</ParamField>
        <ParamField body="enableForecast" type="boolean" default={false}>Show forecast line.</ParamField>
        <ParamField body="showXScrollBar" type="boolean" default={false}>Show horizontal scrollbar.</ParamField>
        <ParamField body="showYScrollBar" type="boolean" default={false}>Show vertical scrollbar.</ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="drillDown" type="string">
      Title of another chart in the same section to use as a drill-down source. Clicking the source chart filters this chart. Resolved to internal chart IDs during import.
    </ParamField>

    <ParamField body="card" type="object">
      KPI metric card styling. Only applicable for `kpi` / `kpi-card` chart types.

      <Expandable title="card properties">
        <ParamField body="icon" type="string">Icon component name (e.g., `"BsCurrencyDollar"`, `"ImCart"`).</ParamField>
        <ParamField body="color" type="string">Primary icon/value color (hex, e.g., `"#237e11"`).</ParamField>
        <ParamField body="trendColor" type="string">Trend-up color (hex, e.g., `"#41d723"`).</ParamField>

        <ParamField body="trend" type="object">
          Trend sparkline configuration for the KPI card.

          <Expandable title="trend properties">
            <ParamField body="field" type="string" required>Measure field to trend (e.g., `"Market Value"`).</ParamField>
            <ParamField body="dateField" type="string" required>Date dimension for the trend x-axis (e.g., `"Position Date"`).</ParamField>
            <ParamField body="interval" type="string" default="Month">Trend grouping interval: `"Day"`, `"Week"`, `"Month"`, `"Quarter"`, `"Year"`.</ParamField>
            <ParamField body="format" type="string" default="percentage">Trend display format: `"percentage"` (delta %), `"absolute"` (delta value), or `"value"`.</ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="bubble" type="object">
      Bubble chart configuration. Only applicable for `bubble` chart type.

      <Expandable title="bubble properties">
        <ParamField body="sizeField" type="string">Field that controls bubble size.</ParamField>

        <ParamField body="xAxis" type="string | object">
          X-axis field. Pass a string for the field name, or an object `{"field": "...", "type": "dimension" | "measure"}`.
        </ParamField>

        <ParamField body="yAxis" type="string | object">
          Y-axis field. Same format as `xAxis`.
        </ParamField>

        <ParamField body="colorField" type="string">Field that controls bubble color intensity.</ParamField>

        <ParamField body="colorRange" type="array">
          Two-element array of hex colors for the min/max color gradient (e.g., `["#98c1e7", "#1169bb"]`).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="sections" type="array">
  Array of section definitions. Use this for **multi-section mode** (multiple experiments, category tabs).

  <Expandable title="section object">
    <ParamField body="name" type="string">
      Section name — appears as the category tab label.
    </ParamField>

    <ParamField body="charts" type="array" required>
      Same chart array format as the top-level `charts` field.
    </ParamField>

    <ParamField body="topSection" type="boolean" default={false}>
      If `true`, this section's charts render in the always-visible top section (ideal for KPI cards).
    </ParamField>

    <ParamField body="category" type="boolean" default={false}>
      If `true`, this section appears as a navigable category tab.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="layout" type="object">
  Layout configuration for the dashboard grid.

  <Expandable title="layout properties">
    <ParamField body="columns" type="number" default={2}>
      Number of columns in the grid.
    </ParamField>

    <ParamField body="chartHeight" type="string" default="380px">
      Default chart height.
    </ParamField>

    <ParamField body="kpiHeight" type="string" default="180px">
      Height for KPI cards in the top section.
    </ParamField>

    <ParamField body="chartWidth" type="string" default="100%">
      Default chart width.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="templateType" type="string">
  Layout template type (e.g., `"realEstate"`). Used to resolve a layout template from the database.
</ParamField>

<ParamField body="layoutTemplateName" type="string">
  Exact name of a layout template. Takes priority over `templateType`.
</ParamField>

<ParamField body="category" type="array">
  Dashboard categories (e.g., `["BI", "Sales"]`).
</ParamField>

<ParamField body="tags" type="array">
  Tags for the dashboard. `"sdk-import"` is always added automatically.
</ParamField>

<ParamField body="isPublic" type="boolean" default={true}>
  Whether the dashboard is publicly visible.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the import succeeded.
</ResponseField>

<ResponseField name="facadeId" type="string">
  The created facade ID (e.g., `F2026A00018`). Use this to view the dashboard in the UI.
</ResponseField>

<ResponseField name="experiments" type="array">
  Array of created experiments.

  <Expandable title="experiment object">
    <ResponseField name="experimentId" type="string">
      Experiment ID (e.g., `E2026A00042`).
    </ResponseField>

    <ResponseField name="section" type="string">
      Section name this experiment belongs to.
    </ResponseField>

    <ResponseField name="charts" type="array">
      Charts created within this experiment.

      <Expandable title="chart object">
        <ResponseField name="chartId" type="string">
          Chart identifier (e.g., `chart_1`).
        </ResponseField>

        <ResponseField name="chartType" type="string">
          Resolved chart type code (e.g., `CH00003`).
        </ResponseField>

        <ResponseField name="chartTitle" type="string">
          Chart display title.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash Simple Mode theme={null}
  curl -X POST https://<your-instance>/v1/sdk/import \
    -H "Authorization: Bearer trvh_sdk_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Revenue Dashboard",
      "dataSource": {
        "dbId": "D2026A00002",
        "vdmId": "VDM2026A00001",
        "connType": "VDM"
      },
      "charts": [
        {
          "title": "Revenue by Region",
          "type": "column",
          "measures": [{"field": "revenue", "aggregation": "sum"}],
          "dimensions": ["region"]
        }
      ],
      "category": ["Sales"],
      "tags": ["quarterly"]
    }'
  ```

  ```bash Sections with Layout & Interactions theme={null}
  curl -X POST https://<your-instance>/v1/sdk/import \
    -H "Authorization: Bearer trvh_sdk_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Executive Dashboard",
      "dataSource": {"dbId": "D2026A00002", "vdmId": "VDM2026A00001", "connType": "VDM"},
      "templateType": "realEstate",
      "sections": [
        {
          "name": "KPIs",
          "topSection": true,
          "charts": [
            {
              "title": "Total Revenue",
              "type": "kpi",
              "measures": [{"field": "revenue", "aggregation": "sum"}],
              "dimensions": ["period"],
              "grid": {"width": 3, "height": 6, "x": 0, "y": 0},
              "card": {
                "icon": "BsCurrencyDollar",
                "color": "#237e11",
                "trend": {"field": "revenue", "dateField": "order_date", "interval": "Month", "format": "percentage"}
              }
            }
          ]
        },
        {
          "name": "Sales",
          "category": true,
          "charts": [
            {
              "title": "Revenue by Region",
              "type": "donut",
              "measures": [{"field": "revenue", "aggregation": "sum"}],
              "dimensions": ["region"],
              "grid": {"width": 4, "height": 13, "x": 0, "y": 0},
              "display": {"showValues": true, "showLegend": true}
            },
            {
              "title": "Revenue by Product",
              "type": "column",
              "measures": [{"field": "revenue", "aggregation": "sum"}],
              "dimensions": ["product"],
              "drillDown": "Revenue by Region",
              "grid": {"width": 8, "height": 13, "x": 4, "y": 0},
              "sort": [{"field": "revenue", "direction": "desc"}]
            }
          ]
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "success": true,
    "facadeId": "F2026A00018",
    "experiments": [
      {
        "experimentId": "E2026A00042",
        "section": "Revenue Dashboard",
        "charts": [
          {
            "chartId": "chart_1",
            "chartType": "CH00003",
            "chartTitle": "Revenue by Region"
          }
        ]
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "success": false,
    "error": "Request body must include a non-empty 'charts' array or 'sections' array with charts"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "API key required"
  }
  ```
</ResponseExample>