Flashboards

Flashboards are persistent dashboards that visualize your data through a composable UI component tree. They can be created from chat, built in Studio, or assembled via API — and shared publicly with token-based links.

Concept

A flashboard combines:

Data snapshots — Query results embedded for offline rendering
UITree — A flat component tree defining layout and visualizations
Versioning — Every save creates an immutable version
Sharing — Token-based public links with optional expiration

Examples:

Flashboard	Components	Data Source
Sales Dashboard	KpiCard, BarChart, DataTable	Gold-layer sales tables
Inventory Status	KpiCard, Heatmap, List	Silver-layer inventory
Customer Insights	PieChart, DataTable, SparklineChart	Gold-layer customer metrics

UITree Schema

A flashboard's layout is defined by a UITree — a flat map of typed components with a root key. Each element has a type, props, and optional children references.

Component Types

Category	Components	Description
Layout	`Grid`, `Card`, `Section`, `Stack`	Structural containers for arranging content
Metrics	`KpiCard`, `Stat`, `ProgressBar`	Single-value and progress displays
Charts	`BarChart`, `AreaChart`, `LineChart`, `PieChart`, `DonutChart`, `SparklineChart`	Data visualizations
Tables	`DataTable`, `List`, `CustomerList`, `InventoryStatus`	Tabular and list displays
Content	`Text`, `Alert`, `Divider`, `ImageWidget`	Static content and messaging
Interactive	`ActionButton`	User-triggered actions

Example UITree

{
  "root": "grid_root",
  "elements": {
    "grid_root": {
      "type": "Grid",
      "props": { "columns": 3, "gap": "md" },
      "children": ["kpi_revenue", "kpi_orders", "chart_trend"]
    },
    "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"
      }
    },
    "chart_trend": {
      "type": "BarChart",
      "props": {
        "title": "Revenue by Month",
        "data": [
          { "month": "Jan", "revenue": 42000 },
          { "month": "Feb", "revenue": 48500 },
          { "month": "Mar", "revenue": 52000 }
        ],
        "xAxis": "month",
        "yAxis": "revenue"
      }
    }
  }
}

UITree elements use a flat map structure with string keys. Children are referenced by key, not nested. This makes updates and patches efficient.

Flashboard Lifecycle

Versioning

Every edit creates a new FlashboardVersion. Versions are immutable and append-only.

Operation	What Happens
Create flashboard	Version 1 is created automatically
Edit flashboard	New version created with incremented `version_number`
Revert to prior version	New version created with the old version's content
List versions	Returns all versions in order

Reverting does not delete versions — it creates a new version with the old content. This preserves the full edit history.

Creation Methods

Ask the assistant to build a dashboard. It uses the create_flashboard tool behind the scenes:

"Build me a dashboard showing this month's revenue KPIs, an order trend chart, and a table of recent orders."

The assistant will:

Query your data to gather metrics
Construct a UITree with appropriate components
Create the flashboard with embedded data snapshots
Return an inline preview in the chat

The Studio provides an interactive AI-powered builder. Send a prompt and receive a streamed flashboard construction:

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 performance dashboard with revenue KPIs and order trends"
  }'

The build endpoint streams SSE events as the flashboard is constructed in real time.

Create a flashboard directly 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": 2 },
          "children": ["kpi_revenue", "kpi_orders"]
        },
        "kpi_revenue": {
          "type": "KpiCard",
          "props": { "title": "Revenue", "value": "$142,500" }
        },
        "kpi_orders": {
          "type": "KpiCard",
          "props": { "title": "Orders", "value": "1,847" }
        }
      }
    }
  }'

Studio Build (SSE)

The Studio build endpoint (POST /api/v1/flashboards/build) uses AI to construct flashboards from natural language prompts. It streams progress via Server-Sent Events.

SSE Event Types

Event	Description
`narration`	AI commentary explaining what it's building
`data_snapshot`	Query results being embedded
`patch`	Incremental UITree updates as components are added
`persisted`	Flashboard saved to database with ID
`done`	Build complete

Example Stream

event: narration
data: {"text": "Analyzing your sales data to build KPI cards..."}

event: data_snapshot
data: {"query": "SELECT SUM(total) FROM gold.orders", "rows": [{"sum": 142500}]}

event: patch
data: {"op": "add", "path": "/elements/kpi_revenue", "value": {"type": "KpiCard", ...}}

event: persisted
data: {"flashboard_id": "fb_abc123", "version": 1}

event: done
data: {}

Flashboards can be shared publicly via token-based links. Shared flashboards do not require authentication to view.

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",
    "versionId": "ver_abc123"
  }'

Field	Type	Required	Description
`expiresAt`	datetime	No	When the share link expires (default: never)
`versionId`	string	No	Pin to a specific version (default: latest)

Resolve a Shared Flashboard

GET /api/shared/flashboards/{shareToken}

This endpoint is public — no authentication required. Returns the flashboard spec and embedded data snapshot.

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

Security

Share tokens grant read-only access to the flashboard data. Use expiring tokens for external stakeholders. Revoke tokens when access is no longer needed.

Data Snapshots

Flashboards store query results as dataSnapshot alongside the spec (UITree). This means:

Flashboards render without a live data connection
Historical versions preserve the data as it was at creation time
Shared flashboards include the data in the token response

To refresh a flashboard's data, create a new version. Each version captures a fresh snapshot of the underlying queries.

Best Practices

Start from chat — Describe what you want to see and let AI build the first draft
Use Grid layouts — Grids provide responsive, multi-column layouts that work across screen sizes
Version before major changes — Creating a version gives you an easy rollback point
Share with expiring tokens — Set expiresAt for external stakeholders
Keep queries in gold layer — Gold-layer tables are optimized for analytics performance
Embed data snapshots — Ensures flashboards render reliably even if data sources change

OpenAPI Reference

For detailed endpoint schemas, request/response formats, and authentication:

Flashboard Endpoints

Full OpenAPI documentation for flashboard management, versioning, and sharing

Flashboards

Flashboard Endpoints

On this page