Appearance
Dashboards Module
Overview
Swagger-driven developer documentation for dashboard endpoints and contracts.
- Dashboard CRUD and runtime execution
Key APIs
| Method | Path | Summary |
|---|---|---|
| GET | /api/dashboards | List dashboards |
| POST | /api/dashboards | Create dashboard |
| DELETE | /api/dashboards/{id} | Delete dashboard |
| GET | /api/dashboards/{id} | Get dashboard details |
| PATCH | /api/dashboards/{id} | Update dashboard |
| POST | /api/dashboards/{id}/execute | Execute dashboard runtime |
| POST | /api/dashboards/import | Import dashboard from JSON |
| POST | /api/dashboards/resolve-alias | Resolve dashboard alias to devices |
Frontend Usage Flow
- Frontend list pages call collection
GETendpoints to load tables or summary views. - Detail pages call parameterized
GETendpoints to load a single resource before rendering tabs, forms, or detail sections. - Create forms submit payloads to
POSTendpoints and then refresh the list or navigate to the created resource. - Edit flows load existing values, submit to
PUTorPATCHendpoints, and then refresh the visible state. - Delete actions call
DELETEendpoints and then refresh collection state.
GET /api/dashboards
Summary: List dashboards
Operation ID: DashboardsController_list
Tags: Dashboards
Security:
bearer
Responses
200
Dashboards returned successfully
Content-Type: application/json
Schema:
json
{
"type": "array",
"items": {
"$ref": "#/components/schemas/DashboardResponseDto"
}
}Example:
json
[
{
"id": "dashboard-123",
"name": "Main Plant Dashboard",
"type": "STATIC",
"tenantId": "tenant-123",
"states": [
{
"id": "default",
"name": "Default"
}
],
"layout": [
{
"i": "widget-1",
"x": 0,
"y": 0,
"w": 8,
"h": 6
}
],
"widgets": [
{
"widgetId": "widget-1",
"type": "timeseries",
"name": "Temperature widget",
"config": {}
}
],
"aliases": [
{
"id": "alias-1",
"name": "Selected Device",
"type": "dashboardState"
}
],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
},
"createdAt": "2026-04-07T08:00:00.000Z",
"updatedAt": "2026-04-07T08:30:00.000Z"
}
]401
Unauthorized
No response body.
Notes / Constraints
- Swagger declares security requirements for this operation.
POST /api/dashboards
Summary: Create dashboard
Operation ID: DashboardsController_create
Tags: Dashboards
Security:
bearer
Request
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Dashboard display name"
},
"type": {
"type": "string",
"description": "Dashboard type (optional, defaults to STATIC)",
"enum": [
"STATIC",
"CONTEXT_DEVICE"
]
},
"states": {
"type": "array",
"description": "Optional dashboard states",
"items": {
"type": "string"
}
},
"layout": {
"type": "array",
"description": "Optional widget layout items",
"items": {
"type": "string"
}
},
"widgets": {
"type": "array",
"description": "Optional dashboard widgets",
"items": {
"type": "string"
}
},
"aliases": {
"type": "array",
"description": "Optional dashboard aliases",
"items": {
"type": "string"
}
},
"timeWindow": {
"type": "object",
"description": "Optional dashboard time window"
},
"configuration": {
"type": "object",
"description": "Optional legacy dashboard configuration payload"
},
"settings": {
"type": "object",
"description": "Optional additional settings payload"
}
}
}Example:
json
{
"name": "Main Plant Dashboard",
"type": "STATIC",
"states": [
{
"id": "default",
"name": "Default"
}
],
"layout": [],
"widgets": [],
"aliases": [],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
}
}Responses (2)
201
Dashboard created successfully
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"STATIC",
"CONTEXT_DEVICE"
]
},
"tenantId": {
"type": "string"
},
"states": {
"type": "array",
"description": "Dashboard states",
"items": {
"type": "string"
}
},
"layout": {
"type": "array",
"description": "Dashboard layout items",
"items": {
"type": "string"
}
},
"widgets": {
"type": "array",
"description": "Dashboard widgets",
"items": {
"type": "string"
}
},
"aliases": {
"type": "array",
"description": "Dashboard aliases",
"items": {
"type": "string"
}
},
"timeWindow": {
"type": "object",
"description": "Dashboard time window"
},
"configuration": {
"type": "object",
"description": "Legacy configuration payload"
},
"settings": {
"type": "object",
"description": "Additional settings payload"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}Example:
json
{
"id": "dashboard-123",
"name": "Main Plant Dashboard",
"type": "STATIC",
"tenantId": "tenant-123",
"states": [
{
"id": "default",
"name": "Default"
}
],
"layout": [
{
"i": "widget-1",
"x": 0,
"y": 0,
"w": 8,
"h": 6
}
],
"widgets": [
{
"widgetId": "widget-1",
"type": "timeseries",
"name": "Temperature widget",
"config": {}
}
],
"aliases": [
{
"id": "alias-1",
"name": "Selected Device",
"type": "dashboardState"
}
],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
},
"createdAt": "2026-04-07T08:00:00.000Z",
"updatedAt": "2026-04-07T08:30:00.000Z"
}400
Invalid dashboard payload
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"statusCode",
"error"
],
"properties": {
"statusCode": {
"type": "number"
},
"error": {
"type": "string"
},
"message": {
"type": "object"
}
}
}Example:
json
{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid time range"
}401 (2)
Unauthorized
No response body.
Notes / Constraints (2)
- Supported request content types:
application/json. - Swagger declares security requirements for this operation.
DELETE /api/dashboards/{id}
Summary: Delete dashboard
Operation ID: DashboardsController_delete
Tags: Dashboards
Security:
bearer
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | yes | string | Dashboard identifier |
Responses (3)
200 (2)
Dashboard deleted successfully
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"success"
],
"properties": {
"success": {
"type": "boolean"
}
}
}Example:
json
{
"success": true
}401 (3)
Unauthorized
No response body.
Notes / Constraints (3)
- This endpoint depends on one or more path parameters.
- Swagger declares security requirements for this operation.
GET /api/dashboards/{id}
Summary: Get dashboard details
Operation ID: DashboardsController_get
Tags: Dashboards
Security:
bearer
Parameters (2)
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | yes | string | Dashboard identifier |
Responses (4)
200 (3)
Dashboard returned successfully
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"STATIC",
"CONTEXT_DEVICE"
]
},
"tenantId": {
"type": "string"
},
"states": {
"type": "array",
"description": "Dashboard states",
"items": {
"type": "string"
}
},
"layout": {
"type": "array",
"description": "Dashboard layout items",
"items": {
"type": "string"
}
},
"widgets": {
"type": "array",
"description": "Dashboard widgets",
"items": {
"type": "string"
}
},
"aliases": {
"type": "array",
"description": "Dashboard aliases",
"items": {
"type": "string"
}
},
"timeWindow": {
"type": "object",
"description": "Dashboard time window"
},
"configuration": {
"type": "object",
"description": "Legacy configuration payload"
},
"settings": {
"type": "object",
"description": "Additional settings payload"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}Example:
json
{
"id": "dashboard-123",
"name": "Main Plant Dashboard",
"type": "STATIC",
"tenantId": "tenant-123",
"states": [
{
"id": "default",
"name": "Default"
}
],
"layout": [
{
"i": "widget-1",
"x": 0,
"y": 0,
"w": 8,
"h": 6
}
],
"widgets": [
{
"widgetId": "widget-1",
"type": "timeseries",
"name": "Temperature widget",
"config": {}
}
],
"aliases": [
{
"id": "alias-1",
"name": "Selected Device",
"type": "dashboardState"
}
],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
},
"createdAt": "2026-04-07T08:00:00.000Z",
"updatedAt": "2026-04-07T08:30:00.000Z"
}401 (4)
Unauthorized
No response body.
Notes / Constraints (4)
- This endpoint depends on one or more path parameters.
- Swagger declares security requirements for this operation.
PATCH /api/dashboards/{id}
Summary: Update dashboard
Operation ID: DashboardsController_update
Tags: Dashboards
Security:
bearer
Parameters (3)
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | yes | string | Dashboard identifier |
Request (2)
Content-Type: application/json
Schema:
json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Dashboard display name"
},
"type": {
"type": "string",
"description": "Dashboard type",
"enum": [
"STATIC",
"CONTEXT_DEVICE"
]
},
"states": {
"type": "array",
"description": "Dashboard states list",
"items": {
"type": "string"
}
},
"layout": {
"type": "array",
"description": "Dashboard layout items",
"items": {
"type": "string"
}
},
"widgets": {
"type": "array",
"description": "Dashboard widgets",
"items": {
"type": "string"
}
},
"aliases": {
"type": "array",
"description": "Dashboard aliases",
"items": {
"type": "string"
}
},
"timeWindow": {
"type": "object",
"description": "Dashboard time window payload"
},
"configuration": {
"type": "object",
"description": "Optional legacy dashboard configuration payload"
},
"settings": {
"type": "object",
"description": "Optional additional dashboard settings"
}
}
}Example:
json
{
"name": "Updated Dashboard Name",
"type": "CONTEXT_DEVICE",
"states": [
{
"id": "default",
"name": "Default"
},
{
"id": "state-1",
"name": "Overview"
}
],
"layout": [
{
"i": "widget-1",
"x": 0,
"y": 0,
"w": 8,
"h": 6
}
],
"widgets": [
{
"widgetId": "widget-1",
"type": "timeseries",
"name": "Temperature widget",
"config": {},
"dashboardStateId": "default"
}
],
"aliases": [
{
"id": "alias-1",
"name": "Selected Device",
"type": "dashboardState"
}
],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
}
}Responses (5)
200 (4)
Dashboard updated successfully
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"STATIC",
"CONTEXT_DEVICE"
]
},
"tenantId": {
"type": "string"
},
"states": {
"type": "array",
"description": "Dashboard states",
"items": {
"type": "string"
}
},
"layout": {
"type": "array",
"description": "Dashboard layout items",
"items": {
"type": "string"
}
},
"widgets": {
"type": "array",
"description": "Dashboard widgets",
"items": {
"type": "string"
}
},
"aliases": {
"type": "array",
"description": "Dashboard aliases",
"items": {
"type": "string"
}
},
"timeWindow": {
"type": "object",
"description": "Dashboard time window"
},
"configuration": {
"type": "object",
"description": "Legacy configuration payload"
},
"settings": {
"type": "object",
"description": "Additional settings payload"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}Example:
json
{
"id": "dashboard-123",
"name": "Main Plant Dashboard",
"type": "STATIC",
"tenantId": "tenant-123",
"states": [
{
"id": "default",
"name": "Default"
}
],
"layout": [
{
"i": "widget-1",
"x": 0,
"y": 0,
"w": 8,
"h": 6
}
],
"widgets": [
{
"widgetId": "widget-1",
"type": "timeseries",
"name": "Temperature widget",
"config": {}
}
],
"aliases": [
{
"id": "alias-1",
"name": "Selected Device",
"type": "dashboardState"
}
],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
},
"createdAt": "2026-04-07T08:00:00.000Z",
"updatedAt": "2026-04-07T08:30:00.000Z"
}400 (2)
Invalid dashboard payload
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"statusCode",
"error"
],
"properties": {
"statusCode": {
"type": "number"
},
"error": {
"type": "string"
},
"message": {
"type": "object"
}
}
}Example:
json
{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid time range"
}401 (5)
Unauthorized
No response body.
Notes / Constraints (5)
- This endpoint depends on one or more path parameters.
- Supported request content types:
application/json. - Swagger declares security requirements for this operation.
POST /api/dashboards/{id}/execute
Summary: Execute dashboard runtime
Operation ID: DashboardsController_execute
Tags: Dashboards
Security:
bearer
Parameters (4)
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | yes | string | Dashboard identifier |
Request (3)
Content-Type: application/json
Schema:
json
{
"type": "object",
"properties": {
"timeRange": {
"type": "object",
"description": "Requested runtime time range"
},
"dashboardStateId": {
"type": "string",
"description": "Dashboard state id to execute"
},
"context": {
"type": "object",
"description": "Execution context payload"
}
}
}Example:
json
{
"timeRange": {
"type": "LAST_24_HOURS"
},
"dashboardStateId": "default",
"context": {
"deviceId": "device-123"
}
}Responses (6)
200 (5)
Dashboard executed successfully
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"STATIC",
"CONTEXT_DEVICE"
]
},
"tenantId": {
"type": "string"
},
"states": {
"type": "array",
"description": "Dashboard states",
"items": {
"type": "string"
}
},
"layout": {
"type": "array",
"description": "Dashboard layout items",
"items": {
"type": "string"
}
},
"widgets": {
"type": "array",
"description": "Dashboard widgets",
"items": {
"type": "string"
}
},
"aliases": {
"type": "array",
"description": "Dashboard aliases",
"items": {
"type": "string"
}
},
"timeWindow": {
"type": "object",
"description": "Dashboard time window"
},
"configuration": {
"type": "object",
"description": "Legacy configuration payload"
},
"settings": {
"type": "object",
"description": "Additional settings payload"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}Example:
json
{
"id": "dashboard-123",
"name": "Main Plant Dashboard",
"type": "STATIC",
"tenantId": "tenant-123",
"states": [
{
"id": "default",
"name": "Default"
}
],
"layout": [
{
"i": "widget-1",
"x": 0,
"y": 0,
"w": 8,
"h": 6
}
],
"widgets": [
{
"widgetId": "widget-1",
"type": "timeseries",
"name": "Temperature widget",
"config": {}
}
],
"aliases": [
{
"id": "alias-1",
"name": "Selected Device",
"type": "dashboardState"
}
],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
},
"createdAt": "2026-04-07T08:00:00.000Z",
"updatedAt": "2026-04-07T08:30:00.000Z"
}401 (6)
Unauthorized
No response body.
Notes / Constraints (6)
- This endpoint depends on one or more path parameters.
- Supported request content types:
application/json. - Swagger declares security requirements for this operation.
POST /api/dashboards/import
Summary: Import dashboard from JSON
Operation ID: DashboardsController_importDashboard
Tags: Dashboards
Security:
bearer
Responses (7)
200 (6)
Dashboard imported successfully
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"STATIC",
"CONTEXT_DEVICE"
]
},
"tenantId": {
"type": "string"
},
"states": {
"type": "array",
"description": "Dashboard states",
"items": {
"type": "string"
}
},
"layout": {
"type": "array",
"description": "Dashboard layout items",
"items": {
"type": "string"
}
},
"widgets": {
"type": "array",
"description": "Dashboard widgets",
"items": {
"type": "string"
}
},
"aliases": {
"type": "array",
"description": "Dashboard aliases",
"items": {
"type": "string"
}
},
"timeWindow": {
"type": "object",
"description": "Dashboard time window"
},
"configuration": {
"type": "object",
"description": "Legacy configuration payload"
},
"settings": {
"type": "object",
"description": "Additional settings payload"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
}
}
}Example:
json
{
"id": "dashboard-123",
"name": "Main Plant Dashboard",
"type": "STATIC",
"tenantId": "tenant-123",
"states": [
{
"id": "default",
"name": "Default"
}
],
"layout": [
{
"i": "widget-1",
"x": 0,
"y": 0,
"w": 8,
"h": 6
}
],
"widgets": [
{
"widgetId": "widget-1",
"type": "timeseries",
"name": "Temperature widget",
"config": {}
}
],
"aliases": [
{
"id": "alias-1",
"name": "Selected Device",
"type": "dashboardState"
}
],
"timeWindow": {
"from": 1712550000000,
"to": 1712553600000
},
"configuration": {
"states": {},
"configuration": {}
},
"settings": {
"dashboardState": "default"
},
"createdAt": "2026-04-07T08:00:00.000Z",
"updatedAt": "2026-04-07T08:30:00.000Z"
}401 (7)
Unauthorized
No response body.
Notes / Constraints (7)
- Swagger declares security requirements for this operation.
POST /api/dashboards/resolve-alias
Summary: Resolve dashboard alias to devices
Operation ID: DashboardsController_resolveAlias
Tags: Dashboards
Security:
bearer
Request (4)
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"alias"
],
"properties": {
"alias": {
"type": "object",
"description": "Alias definition to resolve"
},
"dashboardState": {
"type": "object",
"description": "Optional dashboard state/context for alias resolution"
}
}
}Example:
json
{
"alias": {
"id": "entity-alias-1",
"filter": {
"type": "singleEntity"
}
},
"dashboardState": {
"entityId": "device-123"
}
}Responses (8)
200 (7)
Alias resolved successfully
Content-Type: application/json
Schema:
json
{
"type": "object",
"properties": {
"devices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResolvedDeviceDto"
}
}
}
}Example:
json
{
"devices": [
null
]
}400 (3)
alias missing
Content-Type: application/json
Schema:
json
{
"type": "object",
"required": [
"statusCode",
"error"
],
"properties": {
"statusCode": {
"type": "number"
},
"error": {
"type": "string"
},
"message": {
"type": "object"
}
}
}Example:
json
{
"statusCode": 400,
"error": "Bad Request",
"message": "Invalid time range"
}401 (8)
Unauthorized
No response body.
Notes / Constraints (8)
- Supported request content types:
application/json. - Swagger declares security requirements for this operation.
Module Notes / Constraints
- Generated from OpenAPI version metadata:
1.0. - 8 operation(s) in this module declare explicit Swagger security requirements.
- HTTP methods present in this module: GET, POST, DELETE, PATCH.
- This file is generated from Swagger/OpenAPI and should be regenerated when controller, DTO, or Swagger decorator changes affect the spec.
