GraphQL reference: dashboard-management

Generated from the schema this service serves, so it cannot fall behind it. The same schema is published as a file for tools and agents.

Endpoint	https://<your-host>/api/dashboard-management/graphql
Auth plane	tenant — The ordinary application plane. Obtain a tenant access token by calling login then selectTenant on user-management, and authorize each call with the capability it names (for example device:write).
Authorize with	tenant access token
Schema file	/schema/dashboard-management.graphql
Described	94 of 94 elements

Queries

dashboard · dashboardVersion · dashboardVersions · dashboards · publishedDashboard

dashboard

Returns the dashboard with the given token, or null if there is none. Requires dashboard:read.

Returns Dashboard

Argument	Type	Description
token	String!	Token of the dashboard.

dashboardVersion

Returns one published version of a dashboard including its definition. Fails if the dashboard or the version does not exist. Requires dashboard:write.

Returns DashboardVersionDetail

Argument	Type	Description
token	String!	Token of the dashboard.
version	Int!	Version number to read.

dashboardVersions

Lists a dashboard's published versions, newest first, one page at a time. Fails if no dashboard has the token. Requires dashboard:read.

Returns [DashboardVersion!]!

Argument	Type	Description
limit	Int	Maximum number of versions to return. Omitted or below 1 means 100; above 1000 is capped at 1000.
offset	Int	Number of the newest versions to skip before the page starts. Omitted or below 1 means 0.
token	String!	Token of the dashboard.

dashboards

Searches the tenant's dashboards, one page at a time. Results carry metadata only; read a definition with the dashboard query. Requires dashboard:read.

Returns DashboardSearchResults!

Argument	Type	Description
criteria	DashboardSearchCriteria!	Filter and page to return.

publishedDashboard

Returns the version of the dashboard that viewers are served, with its definition, or null if there is no dashboard with the token. Fails with code NOT_PUBLISHED if the dashboard exists but has never been published. Requires dashboard:read.

Returns PublishedDashboard

Argument	Type	Description
token	String!	Token of the dashboard.

Mutations

activateDashboardVersion · createDashboard · deleteDashboard · publishDashboard · rollbackDashboard · updateDashboard

activateDashboardVersion

Makes an existing published version the one viewers are served, without touching the draft (its definition and updatedAt are unchanged). Use it to re-serve an older version; rollbackDashboard, by contrast, overwrites the draft. Fails if the dashboard or the version does not exist. Requires dashboard:write.

Returns DashboardSummary!

Argument	Type	Description
token	String!	Token of the dashboard.
version	Int!	Version number to serve.

createDashboard

Creates a dashboard and returns it. Requires dashboard:write.

Returns Dashboard!

Argument	Type	Description
request	DashboardCreateRequest!	The new dashboard's fields.

deleteDashboard

Permanently deletes a dashboard and all of its published versions. Returns false if no dashboard has the token. The token can be reused immediately. Requires dashboard:write.

Returns Boolean!

Argument	Type	Description
token	String!	Token of the dashboard to delete.

publishDashboard

Freezes the current draft into a new immutable version, numbered one above the latest, makes it the version viewers are served, and returns the version together with the dashboard. The draft's updatedAt is not moved by a publish. Requires dashboard:write.

Returns DashboardPublication!

Argument	Type	Description
description	String	Optional notes for the version.
expectedUpdatedAt	String	Optional precondition: the updatedAt you last read. If the draft has changed since, publishing is refused with the same error as updateDashboard.
label	String	Optional label for the version, such as a release name.
token	String!	Token of the dashboard to publish.

rollbackDashboard

Copies a published version's definition back into the draft, replacing the whole draft definition, and returns the dashboard. The version history is unchanged. Requires dashboard:write.

Returns Dashboard!

Argument	Type	Description
expectedUpdatedAt	String	Optional precondition: the updatedAt you last read. Because a rollback replaces the whole draft, it is refused with the same error as updateDashboard if the draft has changed since.
token	String!	Token of the dashboard.
version	Int!	The published version to restore into the draft.

updateDashboard

Partially updates a dashboard's draft and returns it. Requires dashboard:write. An update that names no field writes nothing and leaves updatedAt unchanged.

Returns Dashboard!

Argument	Type	Description
expectedUpdatedAt	String	Optional optimistic-concurrency precondition: the updatedAt you last read. If the dashboard has changed since, the update is refused with "dashboard was modified by another writer; reload and try again" (not the CONFLICT error code) — even when the request names no field.
request	DashboardUpdateRequest!	The fields to change; see DashboardUpdateRequest for omit, set and clear.
token	String!	Token of the dashboard to update.

Objects

Dashboard · DashboardPublication · DashboardSearchResults · DashboardSummary · DashboardVersion · DashboardVersionDetail · PublishedDashboard · SearchResultsPagination

Dashboard

object

A dashboard: a named, tenant-owned layout of widgets and the data each widget shows. What you edit is the draft; publishDashboard freezes it into an immutable DashboardVersion.

Field	Type	Description
createdAt	String	When the dashboard was created, as an RFC 3339 timestamp.
definition	String!	The current DRAFT definition. The draft is author-only: reading it requires dashboard:write, and a caller holding only dashboard:read is refused with an authorization error rather than served an empty string. Viewers read the published snapshot with the publishedDashboard query instead.
description	String	Free-text description of what the dashboard is for.
id	ID!	Server-assigned identifier. Address a dashboard by its token, not by this.
name	String	Human-readable name shown in dashboard lists.
publishedAt	String	When the served version was published, as an RFC 3339 timestamp; null if never published.
publishedVersion	Int	The version number viewers are served, or null if the dashboard has never been published.
token	String!	Unique, caller-chosen identifier of the dashboard within the tenant.
updatedAt	String	When the dashboard was last written, as an RFC 3339 timestamp. Pass it back as expectedUpdatedAt to make an update, publish or rollback conditional on nobody else having changed the dashboard since you read it.

DashboardPublication

object

What a publish returns: the version it minted, and the dashboard as it stands. A publish does not edit the draft, so the dashboard's updatedAt is unchanged by it; keep using it as your expectedUpdatedAt baseline.

Field	Type	Description
dashboard	DashboardSummary!	The dashboard after the publish, with its unchanged updatedAt and its new publishedVersion.
version	DashboardVersion!	The version the publish created; it is now the version viewers are served.

DashboardSearchResults

object

One page of dashboards matching a search.

Field	Type	Description
pagination	SearchResultsPagination!	Where this page sits in the full result set.
results	[DashboardSummary!]!	The dashboards on this page, without their definitions.

DashboardSummary

object

A dashboard as listed by the dashboards search: the same metadata as Dashboard, without the definition document. Look a dashboard up by token with the dashboard query to read its definition.

Field	Type	Description
createdAt	String	When the dashboard was created, as an RFC 3339 timestamp.
description	String	Free-text description of what the dashboard is for.
id	ID!	Server-assigned identifier. Address a dashboard by its token, not by this.
name	String	Human-readable name shown in dashboard lists.
publishedVersion	Int	The version number viewers are served, or null if the dashboard has never been published.
token	String!	Unique, caller-chosen identifier of the dashboard within the tenant.
updatedAt	String	When the dashboard was last written, as an RFC 3339 timestamp.

DashboardVersion

object

An immutable published snapshot of a dashboard's definition. Versions are append-only: rolling back copies a version into the draft and deletes nothing.

Field	Type	Description
description	String	Optional notes given at publish time.
label	String	Optional label given at publish time, such as a release name. Not interpreted.
publishedAt	String!	When the version was published, as an RFC 3339 timestamp.
publishedBy	String	Who published it: their username, or their email when there is no username.
version	Int!	Version number, increasing by one with each publish of this dashboard.

DashboardVersionDetail

object

One published version including its definition snapshot. Reading a version body is author-only and requires dashboard:write.

Field	Type	Description
definition	String!	The frozen definition of this version, as a JSON document.
description	String	Optional notes given at publish time.
label	String	Optional label given at publish time. Not interpreted.
publishedAt	String!	When the version was published, as an RFC 3339 timestamp.
publishedBy	String	Who published it: their username, or their email when there is no username.
version	Int!	Version number, increasing by one with each publish of this dashboard.

PublishedDashboard

object

The snapshot of a dashboard that viewers are served: the version the dashboard's published pointer names, with its definition. Unlike the draft, this is readable with dashboard:read.

Field	Type	Description
definition	String!	The served version's definition: a JSON document in the format defined by the @devicechain/dashboards package.
description	String	Free-text description of the dashboard, as it is now.
name	String	Human-readable name of the dashboard, as it is now.
publishedAt	String!	When the served version was published, as an RFC 3339 timestamp.
token	String!	Token of the dashboard.
version	Int!	The served version number.

SearchResultsPagination

object

Where a page of search results sits in the full result set. Positions are 1-based and inclusive.

Field	Type	Description
pageEnd	Int	Position of the last result on this page within the full result set (1-based, inclusive).
pageStart	Int	Position of the first result on this page within the full result set (1-based).
totalRecords	Int	Number of records matching the criteria across all pages.

Input types

DashboardCreateRequest · DashboardSearchCriteria · DashboardUpdateRequest

DashboardCreateRequest

input

Fields for a new dashboard.

Input field	Type	Description
definition	String!	The initial draft definition, as a JSON document of at most 1 MiB.
description	String	Free-text description of what the dashboard is for.
name	String	Human-readable name shown in dashboard lists.
token	String!	Unique identifier for the new dashboard within the tenant.

DashboardSearchCriteria

input

Criteria for searching dashboards.

Input field	Type	Description
name	String	Return only dashboards whose name contains this text. The match is a case-sensitive literal substring match: % and _ in the text are ordinary characters, not wildcards.
pageNumber	Int!	Page to return, starting at 1.
pageSize	Int!	Results per page. Below 1 means the default of 100; above 1000 is capped at 1000.

DashboardUpdateRequest

input

A partial update to a dashboard's draft. Omit a field to leave the stored value alone, send a value to set it, or send an explicit null to clear it. The dashboard is named by the mutation's token argument, so there is no token here.

Input field	Type	Description
definition	String	New draft definition (JSON, at most 1 MiB). Omit it to keep the stored definition; an explicit null is refused, because a dashboard must have a definition.
description	String	New description, or null to clear it.
name	String	New name, or null to clear it.