For the base URL, authentication and errors, see the REST API overview.
GET /v1/users/{user}/dashboards
- Request: GET /v1/users/{user}/dashboards
- Operation: ListDashboards
- Operation ID:
Dashboard_List - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes |
Example request
bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards' \
-H 'Authorization: Bearer YOUR_TOKEN'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
Response example (200)
json
[
{
"created": 1792263090743,
"dashboard": "plant_overview",
"description": "Production KPIs",
"modified": 1792263090743,
"name": "Plant overview"
},
{
"created": 1792263090743,
"dashboard": "fleet",
"description": "Device list and detail app",
"modified": 1792263090743,
"name": "Fleet",
"source": "url"
}
]POST /v1/users/{user}/dashboards
- Request: POST /v1/users/{user}/dashboards
- Operation: CreateDashboard
- Operation ID:
Dashboard_Create - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes |
Request body (application/json, required)
Widget dashboards are designed in the console editor (tabs with widgets). Url dashboards (source: url) render a web page, usually an app in a public file storage that is built with the dashboard SDK (npm package @thinger-io/dashboard-sdk). To show a dashboard on a device, product, asset type, group or project page, store the same object as its 'dashboard' property instead.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
controls | any | no | ||
dashboard | string | yes | Pattern: ^[a-zA-Z0-9_-]{1,32}$ | A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters. |
description | string | no | Maximum length: 255 | |
functions | any | no | ||
name | string | yes | Length: 1 to 255 | |
placeholders | any | no | ||
properties | any | no | ||
source | string | no | One of: widgets, url | |
tabs | array of any | no | ||
url | string | no | Maximum length: 1024 Pattern: ^(/[^/\\]|https://) | |
widgets | array of any | no |
Example request: Empty widget dashboard
bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"dashboard": "plant_overview",
"description": "Production KPIs",
"name": "Plant overview",
"tabs": [
{
"icon": "fas fa-tachometer-alt",
"name": "Main",
"widgets": []
}
]
}'Example body: Url dashboard (SDK app)
json
{
"dashboard": "fleet",
"description": "Device list and detail app",
"name": "Fleet",
"source": "url",
"url": "/v1/users/YOUR_USER/storages/fleet_app/files/"
}Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
GET /v1/users/{user}/dashboards/{dashboard}
- Request: GET /v1/users/{user}/dashboards/
- Operation: ReadDashboardConfig
- Operation ID:
Dashboard_ReadConfig - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes | |
dashboard | path | string | yes |
Example request
bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards/YOUR_DASHBOARD' \
-H 'Authorization: Bearer YOUR_TOKEN'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
Response example (200, Empty widget dashboard)
json
{
"created": 1792263090743,
"dashboard": "plant_overview",
"description": "Production KPIs",
"modified": 1792263090743,
"name": "Plant overview",
"tabs": [
{
"icon": "fas fa-tachometer-alt",
"name": "Main",
"widgets": []
}
]
}Response example (200, Url dashboard (SDK app))
json
{
"created": 1792263090743,
"dashboard": "fleet",
"description": "Device list and detail app",
"modified": 1792263090743,
"name": "Fleet",
"source": "url",
"url": "/v1/users/YOUR_USER/storages/fleet_app/files/"
}PUT /v1/users/{user}/dashboards/{dashboard}
- Request: PUT /v1/users/{user}/dashboards/
- Operation: UpdateDashboard
- Operation ID:
Dashboard_Update - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes | |
dashboard | path | string | yes |
Request body (application/json, required)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
controls | any | no | ||
description | string | no | Maximum length: 255 | |
functions | any | no | ||
name | string | no | Length: 1 to 255 | |
placeholders | any | no | ||
properties | any | no | ||
source | string | no | One of: widgets, url | |
tabs | array of any | no | ||
url | string | no | Maximum length: 1024 Pattern: ^(/[^/\\]|https://) | |
widgets | array of any | no |
Example request: Point to another entry file
bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards/YOUR_DASHBOARD' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"source": "url",
"url": "/v1/users/YOUR_USER/storages/fleet_app/files/device.html"
}'Example body: Rename
json
{
"description": "Production KPIs",
"name": "Plant overview (2026)"
}Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
DELETE /v1/users/{user}/dashboards/{dashboard}
- Request: DELETE /v1/users/{user}/dashboards/
- Operation: DeleteDashboard
- Operation ID:
Dashboard_Delete - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes | |
dashboard | path | string | yes |
Example request
bash
curl -X DELETE 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards/YOUR_DASHBOARD' \
-H 'Authorization: Bearer YOUR_TOKEN'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
GET /v1/users/{user}/dashboards/{dashboard}/clone
- Request: GET /v1/users/{user}/dashboards/{dashboard}/clone
- Operation: CloneDashboardConfig
- Operation ID:
Dashboard_CloneConfig - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes | |
dashboard | path | string | yes |
Example request
bash
curl 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards/YOUR_DASHBOARD/clone' \
-H 'Authorization: Bearer YOUR_TOKEN'Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
POST /v1/users/{user}/dashboards/{dashboard}/clone
- Request: POST /v1/users/{user}/dashboards/{dashboard}/clone
- Operation: CloneDashboard
- Operation ID:
Dashboard_Clone - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes | |
dashboard | path | string | yes |
Request body (application/json, required)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
dashboard | string | yes | Pattern: ^[a-zA-Z0-9_-]{1,32}$ | A unique identifier for resources, consisting of alphanumeric characters, underscores, or hyphens, and limited to 32 characters. |
description | string | no | Maximum length: 255 | A brief description of the resource, providing context or additional information, limited to 255 characters. |
enabled | boolean | no | ||
name | string | no | Maximum length: 255 | The name of the resource, limited to 255 characters. It can include any character. |
Example request: Copy with a new id
bash
curl -X POST 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards/YOUR_DASHBOARD/clone' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"dashboard": "copy_of_dashboard"
}'Example body: Copy with name and description
json
{
"dashboard": "line_2_dashboard",
"description": "Same configuration as the original, for production line 2",
"name": "Line 2 copy"
}Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |
PUT /v1/users/{user}/dashboards/{dashboard}/projects
- Request: PUT /v1/users/{user}/dashboards/{dashboard}/projects
- Operation: UpdateDashboardProjects
- Operation ID:
Dashboard_UpdateProjects - Authentication: access token,
Authorization: Bearer YOUR_TOKEN
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
user | path | string | yes | |
dashboard | path | string | yes |
Request body (application/json, required)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
(body) | array of string | no | Projects the resource belongs to, as <owner>@<project> ids. Replaces the whole list: read the current one first to add or remove a single project; [] removes it from every project. |
Example request: No projects
bash
curl -X PUT 'https://YOUR_SERVER/v1/users/YOUR_USER/dashboards/YOUR_DASHBOARD/projects' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '[]'Example body: One project
json
[
"YOUR_USER@greenhouse"
]Example body: Two projects
json
[
"YOUR_USER@greenhouse",
"YOUR_USER@maintenance"
]Responses
| Status | Description |
|---|---|
| 200 | ok |
| 401 | unauthorized |
| 403 | forbidden |