Dashboards API

API for dashboard management.

Overview

Through the Dashboards API, you can 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 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	List of widgets
tags	array	No	List of tags
owner	string	No	Owner ID
shared	boolean	No	Sharing 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 updated.

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

Field	Type	Description
name	string	Dashboard name
description	string	Description
widgets	array	List of widgets
groups	array	List of groups
tags	array	List of tags
owner	string	Owner ID
shared	boolean	Sharing 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 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 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 dashboard
curl -X DELETE https://api.dhub.io/api/v1/dashboards/dashboard-abc123 \
  -H "Authorization: Bearer <access_token>"