Dashboards API Reference

Manage business dashboards, widgets, and dashboard-related operations in the analytics system.

Base Path: /api/dashboards

Overview

The Dashboards API provides endpoints for managing custom dashboards including creation, widget management, and user-specific dashboard assignments. Supports multiple dashboard widgets with real-time data.

Key Operations

API Endpoints

POST /api/dashboards

Create Dashboard

Creates a new custom dashboard.

Authentication

Bearer Token

Request Body

{
  "name": "Executive Summary",
  "description": "Key metrics and KPIs",
  "type": "executive",
  "widgets": [
    {
      "id": "widget_1",
      "type": "revenue_chart",
      "title": "Monthly Revenue",
      "size": "large"
    },
    {
      "id": "widget_2",
      "type": "active_subscriptions",
      "title": "Active Subscriptions",
      "size": "small"
    }
  ],
  "refreshInterval": 60
}

Response

{
  "id": "dashboard_123",
  "name": "Executive Summary",
  "type": "executive",
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/dashboards/{id}

Get Dashboard by ID

Gets dashboard details by ID with all widgets.

Authentication

Bearer Token

Path Parameters

Parameter Type
id string

Response

{
  "id": "dashboard_123",
  "name": "Executive Summary",
  "description": "Key metrics and KPIs",
  "type": "executive",
  "widgets": [
    {
      "id": "widget_1",
      "type": "revenue_chart",
      "title": "Monthly Revenue",
      "size": "large",
      "data": {
        "series": [{"month": "Jan", "value": 5000}]
      }
    }
  ],
  "refreshInterval": 60,
  "createdAt": "2026-06-02T10:30:00Z"
}
GET /api/dashboards

List Dashboards

Gets all dashboards with pagination.

Authentication

Bearer Token

Query Parameters

Parameter Type Description
$filter string OData filter expression
$skip integer Skip n records
$top integer Take n records

Response

{
  "value": [
    {
      "id": "dashboard_123",
      "name": "Executive Summary",
      "type": "executive",
      "widgetCount": 5,
      "createdAt": "2026-06-02T10:30:00Z"
    }
  ],
  "count": 20
}
PUT /api/dashboards/{id}

Update Dashboard

Updates dashboard definition and layout.

Authentication

Bearer Token

Request Body

{
  "name": "Executive Summary - Updated",
  "description": "Updated key metrics and KPIs",
  "refreshInterval": 90,
  "widgets": [
    {
      "id": "widget_1",
      "type": "revenue_chart",
      "title": "Quarterly Revenue",
      "size": "large"
    }
  ]
}

Response

{
  "id": "dashboard_123",
  "name": "Executive Summary - Updated",
  "updatedAt": "2026-06-02T11:00:00Z"
}
DELETE /api/dashboards/{id}

Delete Dashboard

Deletes a dashboard and its widgets.

Authentication

Bearer Token

Response

{
  "success": true,
  "message": "Dashboard deleted"
}
GET /api/dashboards/by-user/{userId}

Get User Dashboards

Gets all dashboards assigned to a specific user.

Authentication

Bearer Token

Path Parameters

Parameter Type
userId string

Response

{
  "userId": 123,
  "dashboards": [
    {
      "id": "dashboard_123",
      "name": "Executive Summary",
      "type": "executive",
      "isDefault": true
    },
    {
      "id": "dashboard_124",
      "name": "Sales Performance",
      "type": "sales",
      "isDefault": false
    }
  ]
}

Error Responses

Code HTTP Status Description
DASHBOARD_NOT_FOUND 404 Dashboard does not exist
USER_NOT_FOUND 404 User does not exist
INVALID_WIDGET_TYPE 400 Widget type is not supported
DUPLICATE_DASHBOARD 409 Dashboard name already exists

Quick Links

← Back to Overview ← Reports API Organizations API → Try the Playground