Dashboard Endpoints

The Dashboard API provides full CRUD operations for dashboards and their widgets, enabling users to build, manage, and share analytical dashboards. Dashboards are composed of configurable widgets that display charts, tables, KPIs, and other data visualizations backed by SQL queries or metric definitions.

Create Dashboard

Creates a new dashboard for the authenticated tenant.

Property	Value
Method	`POST`
Path	`/api/v1/bi/dashboards`
Auth	JWT required

Request Body

{
  "name": "Q4 Revenue Dashboard",
  "description": "Quarterly revenue analysis across regions",
  "visibility": "private",
  "tags": ["revenue", "quarterly"],
  "filters": [
    {
      "field": "region",
      "operator": "in",
      "values": ["US", "EU", "APAC"]
    }
  ]
}

Response

{
  "id": "dash-abc123",
  "name": "Q4 Revenue Dashboard",
  "tenant_id": "acme-corp",
  "created_by": "user-456",
  "visibility": "private",
  "widget_count": 0,
  "created_at": "2025-03-15T10:00:00Z"
}

List Dashboards

Lists dashboards accessible to the authenticated user.

Property	Value
Method	`GET`
Path	`/api/v1/bi/dashboards`
Auth	JWT required

Query Parameters

Parameter	Type	Required	Description
visibility	string	no	Filter by visibility (private, team, public)
tag	string	no	Filter by tag
limit	integer	no	Max results (default 20)
offset	integer	no	Pagination offset

Get Dashboard

Retrieves a dashboard with all its widgets and configuration.

Property	Value
Method	`GET`
Path	`/api/v1/bi/dashboards/:dashboard_id`
Auth	JWT required

Update Dashboard

Updates dashboard metadata such as name, description, visibility, or filters.

Property	Value
Method	`PUT`
Path	`/api/v1/bi/dashboards/:dashboard_id`
Auth	JWT required (owner or admin)

Delete Dashboard

Deletes a dashboard and all its widgets.

Property	Value
Method	`DELETE`
Path	`/api/v1/bi/dashboards/:dashboard_id`
Auth	JWT required (owner or admin)

Add Widget

Adds a widget to an existing dashboard. Widgets are positioned on a 12-column grid system.

Property	Value
Method	`POST`
Path	`/api/v1/bi/dashboards/:dashboard_id/widgets`
Auth	JWT required

Request Body

{
  "name": "Revenue by Region",
  "widget_type": "bar_chart",
  "position": {
    "x": 0,
    "y": 0,
    "width": 6,
    "height": 4
  },
  "data_source": {
    "sql": "SELECT region, SUM(revenue) FROM sales GROUP BY region",
    "cache_ttl_seconds": 300
  },
  "config": {
    "x_axis": "region",
    "y_axis": "sum_revenue",
    "color_scheme": "blue",
    "show_legend": true
  }
}

Widget Types

Type	Description
`bar_chart`	Vertical or horizontal bar chart
`line_chart`	Time series or trend line
`pie_chart`	Proportional distribution
`area_chart`	Filled area chart
`scatter_plot`	Two-variable scatter
`kpi_card`	Single metric display with trend
`table`	Tabular data display
`heatmap`	Two-dimensional heatmap
`text`	Markdown text block

Update Widget

Updates an existing widget configuration or position.

Property	Value
Method	`PUT`
Path	`/api/v1/bi/dashboards/:dashboard_id/widgets/:widget_id`
Auth	JWT required

Delete Widget

Removes a widget from a dashboard.

Property	Value
Method	`DELETE`
Path	`/api/v1/bi/dashboards/:dashboard_id/widgets/:widget_id`
Auth	JWT required

Share Dashboard

Configures sharing settings for a dashboard.

Property	Value
Method	`POST`
Path	`/api/v1/bi/dashboards/:dashboard_id/share`
Auth	JWT required (owner or admin)

Request Body

{
  "visibility": "team",
  "shared_with": ["user-789", "team-analytics"],
  "permissions": "view"
}

Chat Endpoints Search Endpoints