Building Flashboards

Flashboards turn your data into persistent, shareable dashboards. This guide walks you through creating, customizing, versioning, and sharing flashboards.

What You'll Build

A sales performance dashboard with:

• Revenue and order count KPIs
• A revenue trend chart
• A recent orders table

Method 1: Create from Chat

The simplest way to build a flashboard. Ask the assistant:

"Build me a dashboard showing this month's revenue and order count as KPIs, a revenue trend chart by week, and a table of the 20 most recent orders."

The assistant will:

1. Query your gold-layer tables for the data
2. Construct a UITree with KpiCards, a BarChart, and a DataTable
3. Embed data snapshots into the components
4. Create the flashboard and return an inline preview

You can then refine it:

"Add a pie chart showing revenue by product category" "Change the chart to show daily instead of weekly"

Method 2: Create via API

For programmatic creation, POST a flashboard with a spec (UITree) definition:

curl -X POST https://vai-dev.virtuousai.com/api/v1/flashboards \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Sales Dashboard",
    "description": "Monthly sales performance overview",
    "spec": {
      "root": "grid_root",
      "elements": {
        "grid_root": {
          "type": "Grid",
          "props": { "columns": 3, "gap": "md" },
          "children": ["kpi_revenue", "kpi_orders", "kpi_aov"]
        },
        "kpi_revenue": {
          "type": "KpiCard",
          "props": {
            "title": "Total Revenue",
            "value": "$142,500",
            "change": "+12.5%",
            "changeDirection": "up"
          }
        },
        "kpi_orders": {
          "type": "KpiCard",
          "props": {
            "title": "Orders",
            "value": "1,847",
            "change": "+8.3%",
            "changeDirection": "up"
          }
        },
        "kpi_aov": {
          "type": "KpiCard",
          "props": {
            "title": "Avg Order Value",
            "value": "$77.12",
            "change": "+3.8%",
            "changeDirection": "up"
          }
        }
      }
    }
  }'

{
  "id": "fb_abc123",
  "title": "Sales Dashboard",
  "description": "Monthly sales performance overview",
  "activeVersionId": "ver_abc123",
  "versionCount": 1,
  "createdAt": "2026-02-08T14:30:00Z",
  "updatedAt": "2026-02-08T14:30:00Z"
}

Method 3: Use Studio

The Studio build endpoint uses AI to construct flashboards from natural language prompts, streaming progress via SSE:

curl -X POST https://vai-dev.virtuousai.com/api/v1/flashboards/build \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "prompt": "Create a sales dashboard with revenue KPIs, a weekly revenue trend chart, and a recent orders table"
  }'

Studio streams events as it builds:

• narration — AI explains what it's constructing
• data_snapshot — Query results being embedded
• patch — UITree updates as components are added
• persisted — Flashboard saved with its ID
• done — Build complete

Customizing Your Flashboard

Update a flashboard's content or metadata:

curl -X PATCH https://vai-dev.virtuousai.com/api/v1/flashboards/{flashboard_id} \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q1 2026 Sales Dashboard",
    "description": "Updated with January and February data"
  }'

Versioning

Every edit creates a new immutable version. Use versioning to track changes and revert if needed.

Create a New Version

curl -X POST https://vai-dev.virtuousai.com/api/v1/flashboards/{flashboard_id}/versions \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": { ... }
  }'

List Versions

curl https://vai-dev.virtuousai.com/api/v1/flashboards/{flashboard_id}/versions \
  -H "Authorization: Bearer $VAI_API_KEY"

Get a Specific Version

curl https://vai-dev.virtuousai.com/api/v1/flashboards/{flashboard_id}/versions/{version_id} \
  -H "Authorization: Bearer $VAI_API_KEY"

Sharing

Share flashboards with anyone via token-based public links.

Create a Share Link

curl -X POST https://vai-dev.virtuousai.com/api/v1/flashboards/{flashboard_id}/shares \
  -H "Authorization: Bearer $VAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresAt": "2026-03-01T00:00:00Z"
  }'

Response includes a shareToken and a public URL:

https://vai-dev.virtuousai.com/shared/flashboards/{shareToken}

This URL works without authentication — anyone with the link can view the flashboard.

Pin to a Version

To ensure the shared view doesn't change when you update the flashboard:

{
  "versionId": "ver_abc123",
  "expiresAt": "2026-03-01T00:00:00Z"
}

Revoke a Share Link

curl -X DELETE https://vai-dev.virtuousai.com/api/v1/flashboards/{flashboard_id}/shares/{share_id} \
  -H "Authorization: Bearer $VAI_API_KEY"

Component Reference

Key components for building flashboards:

For a full list of all 21+ component types, see the Flashboards primitive reference.

Best Practices

1. Start from chat — Describe what you want and let AI build the first draft
2. Use Grid for layout — Grids give you responsive, multi-column layouts
3. Version before major edits — Easy rollback if changes don't work out
4. Set expiring share tokens — Don't leave public links open indefinitely
5. Query gold-layer tables — Gold-layer tables are optimized for analytics performance
6. Embed meaningful titles — Each component should have a clear, descriptive title

Next Steps