Dashboards API

API for dashboard management.

Overview

The Dashboards API allows you to create, retrieve, update, and delete dashboards. Dashboards consist of multiple widgets and are used for data visualization and monitoring.

Endpoints

GET /api/v1/dashboards/

Retrieves a list of all dashboards.

Query Parameters

Parameter	Type	Default	Description
limit	integer	100	Maximum number of items to retrieve
token	string	-	Pagination token

Response

200 OK

{
  "items": {
    "dashboard-abc123": "{\"id\":\"dashboard-abc123\",\"name\":\"Sales Dashboard\",...}",
    "dashboard-xyz789": "{\"id\":\"dashboard-xyz789\",\"name\":\"Marketing Dashboard\",...}"
  },
  "token": "next-page-token"
}

---

GET /api/v1/dashboards/{dashboard_id}/versions

Retrieves the version history of a dashboard.

Path Parameters

Parameter	Type	Required	Description
dashboard_id	string	Yes	Dashboard ID

Response

200 OK

[
  {
    "version_id": "v3",
    "last_modified": "2024-01-20T10:30:00Z",
    "size": 4096
  },
  {
    "version_id": "v2",
    "last_modified": "2024-01-19T15:00:00Z",
    "size": 3584
  }
]

---

GET /api/v1/dashboards/{dashboard_id}

Retrieves a specific dashboard.

Path Parameters

Parameter	Type	Required	Description
dashboard_id	string	Yes	Dashboard ID

Query Parameters

Parameter	Type	Required	Description
dashboard_version	string	No	Retrieve a specific version

Response

200 OK

{
  "id": "dashboard-abc123",
  "name": "Sales Dashboard",
  "description": "Monthly sales overview",
  "widgets": [
    {
      "id": "widget-1",
      "type": "bar_chart",
      "title": "Revenue by Category",
      "position": {"x": 0, "y": 0, "w": 6, "h": 4},
      "config": {
        "dataSource": "dataset-sales",
        "xField": "category",
        "yField": "revenue"
      }
    }
  ],
  "groups": [],
  "tags": ["sales", "monthly"],
  "owner": "user-admin",
  "shared": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-20T10:30:00Z"
}

---

POST /api/v1/dashboards/

Creates a new dashboard.

Request Body

{
  "name": "Sales Dashboard",
  "description": "Monthly sales overview",
  "widgets": [],
  "tags": ["sales"],
  "owner": "user-admin",
  "shared": false
}

Field	Type	Required	Description
name	string	Yes	Dashboard name
description	string	No	Description
widgets	array	No	Widget list
tags	array	No	Tag list
owner	string	No	Owner ID
shared	boolean	No	Shared status (default: false)

Response

200 OK

{
  "item": "dashboard-abc123"
}

---

PUT /api/v1/dashboards/{dashboard_id}

Updates a dashboard.

Path Parameters

Parameter	Type	Required	Description
dashboard_id	string	Yes	Dashboard ID

Request Body

Include only the fields to be modified.

{
  "name": "Updated Dashboard Name",
  "widgets": [...],
  "shared": true
}

Field	Type	Description
name	string	Dashboard name
description	string	Description
widgets	array	Widget list
groups	array	Group list
tags	array	Tag list
owner	string	Owner ID
shared	boolean	Shared status
comment	string	Version comment

Response

200 OK

{
  "message": "Dashboard updated successfully"
}

---

DELETE /api/v1/dashboards/{dashboard_id}

Deletes a dashboard.

Path Parameters

Parameter	Type	Required	Description
dashboard_id	string	Yes	Dashboard ID

Response

200 OK

{
  "message": "Dashboard deleted successfully"
}

Widget Structure

{
  "id": "widget-uuid",
  "type": "bar_chart",
  "title": "Widget Title",
  "position": {
    "x": 0,
    "y": 0,
    "w": 6,
    "h": 4
  },
  "config": {
    "dataMode": "simple",
    "dataSource": "dataset-id",
    "xField": "category",
    "yField": "value",
    "aggregation": "sum"
  }
}

Widget Types

Type	Description
statistic_card	Statistic card
bar_chart	Bar chart
line_chart	Line chart
pie_chart	Pie chart
heatmap	Heatmap
gauge	Gauge
data_table	Data table
map	Map

Usage Examples

cURL

# List dashboards
curl https://api.dhub.io/api/v1/dashboards/ \
  -H "Authorization: Bearer <access_token>"

# Create a dashboard
curl -X POST https://api.dhub.io/api/v1/dashboards/ \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Dashboard",
    "description": "Dashboard description",
    "widgets": [],
    "shared": false
  }'

# Update a dashboard
curl -X PUT https://api.dhub.io/api/v1/dashboards/dashboard-abc123 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "shared": true}'

# Delete a dashboard
curl -X DELETE https://api.dhub.io/api/v1/dashboards/dashboard-abc123 \
  -H "Authorization: Bearer <access_token>"