Dashboards API

REST API endpoints for dashboard management.

Base URL: /api/dashboards

Authentication

All endpoints except public dashboard access require authentication via Bearer token:

Authorization: Bearer <token>

---

Dashboard Operations

Create Dashboard

POST /api/dashboards/

Request Body:

{
  "name": "Sales Dashboard",
  "description": "Monthly sales overview",
  "workspace_id": "uuid-optional",
  "layout": {
    "columns": 12,
    "rowHeight": 80,
    "gap": 16
  },
  "refresh_interval_seconds": 300
}

Response (201 Created):

{
  "id": "uuid",
  "name": "Sales Dashboard",
  "description": "Monthly sales overview",
  "user_id": "user-id",
  "workspace_id": null,
  "layout": { "columns": 12, "rowHeight": 80, "gap": 16 },
  "refresh_interval_seconds": 300,
  "is_public": false,
  "share_token": null,
  "is_archived": false,
  "created_at": "2024-01-15T10:00:00Z",
  "tile_count": 0,
  "owner_name": "John Doe"
}

List Dashboards

GET /api/dashboards/

Query Parameters:

Parameter	Type	Default	Description
workspace_id	UUID	null	Filter by workspace
include_archived	boolean	false	Include archived dashboards
search	string	null	Search in name/description
limit	integer	50	Max results (1-100)
offset	integer	0	Pagination offset

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "Sales Dashboard",
    "description": "Monthly sales overview",
    "tile_count": 6,
    "is_public": false,
    "owner_name": "John Doe",
    "workspace_name": null,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
]

Get Dashboard with Tiles

GET /api/dashboards/{dashboard_id}

Response (200 OK):

{
  "id": "uuid",
  "name": "Sales Dashboard",
  "tiles": [
    {
      "id": "tile-uuid",
      "dashboard_id": "uuid",
      "title": "Revenue by Region",
      "tile_type": "chart",
      "chart_type": "bar",
      "datasource_id": "ds-uuid",
      "catalog": "analytics",
      "schema": "sales",
      "query": "SELECT region, SUM(revenue) FROM sales GROUP BY region",
      "chart_config": { "xField": "region", "yField": "revenue" },
      "grid_x": 0,
      "grid_y": 0,
      "grid_w": 6,
      "grid_h": 4,
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "tile_count": 1,
  "owner_name": "John Doe"
}

Update Dashboard

PUT /api/dashboards/{dashboard_id}

Request Body (all fields optional):

{
  "name": "Updated Name",
  "description": "Updated description",
  "layout": { "columns": 12, "rowHeight": 100, "gap": 20 },
  "refresh_interval_seconds": 600,
  "is_archived": false
}

Delete Dashboard

DELETE /api/dashboards/{dashboard_id}

Response: 204 No Content

Archive Dashboard

POST /api/dashboards/{dashboard_id}/archive

Response: 204 No Content

---

Sharing

Share/Unshare Dashboard

POST /api/dashboards/{dashboard_id}/share

Request Body:

{
  "is_public": true
}

Response (200 OK):

{
  "is_public": true,
  "share_token": "abc123...",
  "share_url": "/dashboards/shared/abc123..."
}

Get Public Dashboard

GET /api/dashboards/shared/{share_token}

No authentication required.

Returns the dashboard structure and tiles (same format as Get Dashboard).

Get Public Dashboard Data

GET /api/dashboards/shared/{share_token}/data

No authentication required.

Returns the latest snapshot data (cached query results, not live queries).

Response (200 OK):

{
  "id": "snapshot-uuid",
  "dashboard_id": "uuid",
  "tile_data": {
    "tile-uuid": {
      "data": {
        "columns": ["region", "revenue"],
        "rows": [
          { "region": "North", "revenue": 150000 },
          { "region": "South", "revenue": 120000 }
        ]
      },
      "error": null,
      "executed_at": "2024-01-15T12:00:00Z"
    }
  },
  "execution_time_ms": 1234,
  "trigger_type": "on_share",
  "created_at": "2024-01-15T12:00:00Z"
}

---

Tile Management

Add Tile

POST /api/dashboards/{dashboard_id}/tiles

Request Body:

{
  "title": "Revenue Chart",
  "tile_type": "chart",
  "chart_type": "bar",
  "datasource_id": "uuid",
  "catalog": "analytics",
  "schema": "sales",
  "query": "SELECT region, revenue FROM sales",
  "chart_config": {
    "xField": "region",
    "yField": "revenue",
    "showLegend": true
  },
  "grid_x": 0,
  "grid_y": 0,
  "grid_w": 6,
  "grid_h": 4
}

Tile Types: chart, kpi, table, text

Chart Types: bar, line, area, pie, scatter, funnel, heatmap, treemap, sankey, chord, radar, gauge

Add Tile from Conversation

POST /api/dashboards/{dashboard_id}/tiles/from-conversation

Add a chart generated in an AI conversation to a dashboard.

Request Body:

{
  "title": "Chart from AI",
  "conversation_id": "conv-id",
  "message_id": "msg-id",
  "chart_type": "bar",
  "query": "SELECT * FROM sales",
  "chart_config": { "xField": "region", "yField": "revenue" },
  "datasource_id": "uuid",
  "catalog": "analytics",
  "schema": "sales",
  "grid_w": 4,
  "grid_h": 3
}

Update Tile

PUT /api/dashboards/{dashboard_id}/tiles/{tile_id}

Request Body (all fields optional):

{
  "title": "Updated Title",
  "query": "SELECT * FROM new_table",
  "chart_config": { "xField": "col1", "yField": "col2" },
  "grid_x": 4,
  "grid_y": 0,
  "grid_w": 8,
  "grid_h": 4
}

Delete Tile

DELETE /api/dashboards/{dashboard_id}/tiles/{tile_id}

Response: 204 No Content

Bulk Update Tile Layouts

PUT /api/dashboards/{dashboard_id}/tiles/layout

Update positions of multiple tiles at once (typically after drag-drop operations).

Request Body:

{
  "layouts": [
    { "tile_id": "uuid-1", "grid_x": 0, "grid_y": 0, "grid_w": 6, "grid_h": 4 },
    { "tile_id": "uuid-2", "grid_x": 6, "grid_y": 0, "grid_w": 6, "grid_h": 4 }
  ]
}

Response: 204 No Content

---

Query Execution

Execute All Tiles

GET /api/dashboards/{dashboard_id}/data

Executes queries for all tiles in the dashboard.

Response (200 OK):

{
  "id": "uuid",
  "name": "Sales Dashboard",
  "tiles": [
    {
      "id": "tile-uuid",
      "title": "Revenue",
      "tile_type": "chart",
      "data": {
        "columns": ["region", "revenue"],
        "rows": [
          { "region": "North", "revenue": 150000 }
        ]
      },
      "error": null,
      "executed_at": "2024-01-15T12:00:00Z"
    }
  ]
}

Execute Single Tile

GET /api/dashboards/{dashboard_id}/tiles/{tile_id}/data

Response (200 OK):

{
  "id": "tile-uuid",
  "title": "Revenue",
  "tile_type": "chart",
  "data": {
    "columns": ["region", "revenue"],
    "rows": [
      { "region": "North", "revenue": 150000 }
    ]
  },
  "error": null,
  "executed_at": "2024-01-15T12:00:00Z"
}

---

Snapshots

Snapshots cache query results for performance and public sharing.

Create Snapshot

POST /api/dashboards/{dashboard_id}/snapshot

Executes all tile queries and caches the results.

Response (201 Created):

{
  "id": "snapshot-uuid",
  "dashboard_id": "uuid",
  "tile_data": { ... },
  "execution_time_ms": 1234,
  "executed_by": "user-id",
  "trigger_type": "manual",
  "created_at": "2024-01-15T12:00:00Z",
  "expires_at": "2024-01-22T12:00:00Z"
}

Get Latest Snapshot

GET /api/dashboards/{dashboard_id}/snapshot/latest

Returns the most recent non-expired snapshot.

---

Chart Configuration Reference

Standard Charts (bar, line, area)

{
  "xField": "category_column",
  "yField": "value_column",
  "seriesField": "group_column",
  "showLegend": true,
  "stacked": false,
  "smooth": false,
  "horizontal": false
}

Pie/Funnel Charts

{
  "nameField": "category_column",
  "valueField": "value_column",
  "showLegend": true
}

Heatmap

{
  "xField": "x_category",
  "yField": "y_category",
  "valueField": "intensity_value"
}

Sankey/Chord

{
  "sourceField": "from_node",
  "targetField": "to_node",
  "valueField": "flow_value"
}

Treemap

{
  "nameField": "label",
  "valueField": "size",
  "categoryField": "group"
}

Gauge

{
  "valueField": "metric_value",
  "min": 0,
  "max": 100
}

KPI Tile

{
  "valueField": "metric_column",
  "prefix": "$",
  "suffix": "M",
  "compareValue": 100,
  "compareLabel": "vs Last Month"
}

Table Tile

{
  "zebra": true,
  "compact": false,
  "pageSize": 10
}

---

Error Responses

400 Bad Request

{
  "detail": "Dashboard name is required"
}

404 Not Found

{
  "detail": "Dashboard not found or access denied"
}

500 Internal Server Error

{
  "detail": "Failed to execute dashboard queries"
}