Dashboards API 🟡 BETA

Endpoints for creating, managing, and querying custom dashboards with configurable widgets and data sources.

Base URL

/api/dashboards

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header.

Endpoints

List / Create Dashboards

GET /api/dashboards

Retrieves all dashboards accessible to the authenticated user.

Response:

{
  "dashboards": [
    {
      "id": "dash_abc123",
      "name": "Sales Overview",
      "description": "Real-time sales metrics",
      "created_by": "user_001",
      "created_at": "2025-06-01T10:00:00Z",
      "updated_at": "2025-06-03T14:30:00Z",
      "widget_count": 6,
      "is_public": true
    }
  ],
  "total": 12,
  "page": 1,
  "limit": 20
}

POST /api/dashboards

Creates a new dashboard.

Request Body:

{
  "name": "Marketing Analytics",
  "description": "Campaign performance dashboard",
  "is_public": true,
  "template_id": "tmpl_001"
}

Response:

{
  "id": "dash_xyz789",
  "name": "Marketing Analytics",
  "description": "Campaign performance dashboard",
  "created_by": "user_001",
  "created_at": "2025-06-04T09:00:00Z",
  "is_public": true
}

Get Dashboard Templates

GET /api/dashboards/templates

Returns available dashboard templates.

Response:

{
  "templates": [
    {
      "id": "tmpl_001",
      "name": "Sales Overview",
      "description": "Pre-configured sales metrics dashboard",
      "category": "sales",
      "widget_count": 8,
      "preview_url": "/templates/sales-overview/preview.png"
    },
    {
      "id": "tmpl_002",
      "name": "System Health",
      "description": "Infrastructure monitoring dashboard",
      "category": "operations",
      "widget_count": 5,
      "preview_url": "/templates/system-health/preview.png"
    }
  ]
}

Get / Update / Delete Dashboard

GET /api/dashboards/:id

Retrieves a single dashboard with its widgets.

Response:

{
  "id": "dash_abc123",
  "name": "Sales Overview",
  "description": "Real-time sales metrics",
  "created_by": "user_001",
  "created_at": "2025-06-01T10:00:00Z",
  "updated_at": "2025-06-03T14:30:00Z",
  "is_public": true,
  "widgets": [
    {
      "widget_id": "wid_001",
      "type": "line_chart",
      "title": "Revenue Trend",
      "position": { "x": 0, "y": 0, "w": 6, "h": 4 },
      "data_source_id": "src_001",
      "config": { "time_range": "30d", "metric": "revenue" }
    }
  ]
}

PUT /api/dashboards/:id

Updates an existing dashboard’s metadata.

Request Body:

{
  "name": "Sales Overview v2",
  "description": "Updated sales metrics with Q2 data",
  "is_public": false
}

Response:

{
  "id": "dash_abc123",
  "name": "Sales Overview v2",
  "updated_at": "2025-06-04T11:00:00Z"
}

DELETE /api/dashboards/:id

Deletes a dashboard and all associated widgets.

Response:

{
  "success": true,
  "message": "Dashboard deleted"
}

Widget Management

POST /api/dashboards/:id/widgets

Adds a new widget to a dashboard.

Request Body:

{
  "type": "stat_card",
  "title": "Total Revenue",
  "data_source_id": "src_001",
  "position": { "x": 0, "y": 0, "w": 3, "h": 2 },
  "config": {
    "metric": "revenue",
    "aggregation": "sum",
    "time_range": "30d",
    "format": "currency",
    "currency": "USD"
  }
}

Response:

{
  "widget_id": "wid_002",
  "type": "stat_card",
  "title": "Total Revenue",
  "dashboard_id": "dash_abc123",
  "created_at": "2025-06-04T11:00:00Z"
}

PUT /api/dashboards/:id/widgets/:widget_id

Updates an existing widget’s configuration.

Request Body:

{
  "title": "Total Revenue (USD)",
  "config": {
    "metric": "revenue",
    "aggregation": "sum",
    "time_range": "90d",
    "format": "currency",
    "currency": "USD"
  }
}

Response:

{
  "widget_id": "wid_002",
  "title": "Total Revenue (USD)",
  "updated_at": "2025-06-04T12:00:00Z"
}

DELETE /api/dashboards/:id/widgets/:widget_id

Removes a widget from a dashboard.

Response:

{
  "success": true,
  "message": "Widget removed"
}

Widget Data

GET /api/dashboards/:id/widgets/:widget_id/data

Fetches the data payload for a specific widget.

Response (line_chart):

{
  "widget_id": "wid_001",
  "type": "line_chart",
  "data": {
    "labels": ["2025-06-01", "2025-06-02", "2025-06-03", "2025-06-04"],
    "series": [
      {
        "name": "Revenue",
        "values": [12500, 14200, 13800, 16100]
      }
    ]
  },
  "generated_at": "2025-06-04T12:00:00Z"
}

Response (stat_card):

{
  "widget_id": "wid_002",
  "type": "stat_card",
  "data": {
    "value": 56780.50,
    "label": "Total Revenue",
    "format": "currency",
    "currency": "USD",
    "change_percent": 12.5,
    "change_direction": "up"
  },
  "generated_at": "2025-06-04T12:00:00Z"
}

Data Sources

GET /api/dashboards/sources

Lists all configured data sources.

Response:

{
  "sources": [
    {
      "id": "src_001",
      "name": "Sales Database",
      "type": "postgresql",
      "host": "tables.local",
      "database": "sales",
      "status": "connected",
      "last_sync": "2025-06-04T11:55:00Z"
    },
    {
      "id": "src_002",
      "name": "Analytics API",
      "type": "rest_api",
      "endpoint": "https://analytics.internal/api",
      "status": "connected",
      "last_sync": "2025-06-04T12:00:00Z"
    }
  ]
}

POST /api/dashboards/sources

Registers a new data source.

Request Body:

{
  "name": "Inventory DB",
  "type": "postgresql",
  "config": {
    "host": "tables.local",
    "port": 5432,
    "database": "inventory",
    "user": "reader",
    "password": "s3cur3_p4ss",
    "ssl": true
  }
}

Response:

{
  "id": "src_003",
  "name": "Inventory DB",
  "type": "postgresql",
  "status": "connected",
  "created_at": "2025-06-04T12:00:00Z"
}

POST /api/dashboards/sources/:id/test

Tests connectivity to a data source.

Response:

{
  "source_id": "src_003",
  "status": "ok",
  "latency_ms": 12,
  "message": "Connection successful"
}

DELETE /api/dashboards/sources/:id

Removes a data source. Dashboards using this source will show errors.

Response:

{
  "success": true,
  "message": "Data source removed"
}

Ad-hoc Query

POST /api/dashboards/query

Executes an ad-hoc query against a registered data source.

Request Body:

{
  "source_id": "src_001",
  "query": "SELECT date_trunc('day', created_at) AS day, SUM(amount) AS revenue FROM orders WHERE created_at > NOW() - INTERVAL '30 days' GROUP BY day ORDER BY day",
  "limit": 50
}

Response:

{
  "source_id": "src_001",
  "columns": ["day", "revenue"],
  "rows": [
    ["2025-06-01T00:00:00Z", 12500.00],
    ["2025-06-02T00:00:00Z", 14200.50],
    ["2025-06-03T00:00:00Z", 13800.75]
  ],
  "row_count": 3,
  "execution_time_ms": 45
}

Widget Types

Response Codes

See Also

• Monitoring API — system health and metrics
• Analytics API — deep analytics endpoints
• Reports API — static report generation