Dashboard
The widget grid a tenant arranges for one website — what is on it, where, and how each tile is configured — plus dashboard_widget_types, the platform’s catalogue of tiles it can hold. The dashboard is a singleton that always exists: read it before anything was ever saved and it answers with the default layout, and :reset puts that layout back.
List dashboard_widget_types
Every tile a dashboard can hold, with what it shows, how big it may be and what it can be configured with. Nothing here is stored or writable: it is the platform's catalogue, and a type your client does not recognise is one it should draw as a placeholder rather than drop — that is what lets the platform ship a new tile before your client knows about it. A saved dashboard is validated against this same list.
query Parameters
page_sizeRows per page. Over the maximum is clamped, not rejected.
page_tokenOpaque token from a previous next_page_token. A token minted under a different order_by/filter is rejected.
skipRows to skip before the page (AIP-158). skip + page_size is capped at 10000; beyond that is OUT_OF_RANGE.
order_byComma-separated field [asc|desc], at most 3 keys. Default: create_time desc. Sortable: none — this collection serves its documented order only.
filterAIP-160 subset (§8). Filterable: none. A field outside the list is INVALID_ARGUMENT.
List dashboard_widget_types › Responses
One page of dashboard_widget_types.
This page of dashboard_widget_types, in the requested order.
next_page_tokenOpaque. Absent or empty means this was the last page.
total_sizeRows in the whole filtered collection, not in this page.
Get dashboard_widget_type
Every tile a dashboard can hold, with what it shows, how big it may be and what it can be configured with. Nothing here is stored or writable: it is the platform's catalogue, and a type your client does not recognise is one it should draw as a placeholder rather than drop — that is what lets the platform ship a new tile before your client knows about it. A saved dashboard is validated against this same list.
path Parameters
dashboard_widget_type_idId of the parent dashboard_widget_type.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get dashboard_widget_type › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
idThe last segment of name on its own, for a client that needs to build a child URL. Unique inside its parent, never across the platform.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
display_nameThe tile's name as a person reads it, for the «add widget» drawer and the tile's own header.
descriptionWhat the tile shows and — where it matters — what its number leaves out, in a sentence or two the drawer and the tile can show as help text.
categoryWhich section of the «add widget» drawer this tile belongs to: ANALYTICS, CONTENT or PLATFORM.
visualizationHow the tile is drawn: KPI (one number with its trend), LINE_CHART, BAR_CHART, or CUSTOM — which means the admin has a renderer of its own for this id.
metric_idFor an analytics tile, the analytics_metrics id it draws — the row whose :query answers its number. Absent on every other tile.
default_size{width, height} in grid cells — the size the tile is added at when somebody picks it out of the drawer.
min_sizeThe smallest {width, height} this tile still reads at. A saved layout below it is INVALID_ARGUMENT, and a resize handle stops here.
max_sizeThe largest {width, height} this tile is worth. It is a range together with min_size, not a list of allowed sizes — a tile that has exactly one size says so by making the two equal.
singleton_per_dashboardTrue for a tile that makes sense at most once on a page — a checklist, a summary of the whole site. A second one is refused on Update rather than drawn twice.
setting_descriptorsWhat this tile can be configured with: {key, display_name, type, default, allowed_values} per setting. It is what the widget's settings drawer is built from and what a saved widget.settings is validated against — a key that is not here, or a value outside allowed_values, is refused.
Get dashboard
Reads the dashboard of one website. A website whose dashboard nobody has arranged yet gets the platform's default layout back rather than a 404 — there is exactly one dashboard per website and it always exists, implicitly.
That default answer carries is_default: true and no etag and no timestamps: nothing has been stored, so there is nothing to be a version of. Reading it stores nothing either, so a site that never touches its dashboard costs no document and gains every tile a later release adds to the default.
path Parameters
website_idId of the parent website.
Headers
If-None-MatchA matching etag answers 304 with no body (§16).
Get dashboard › Responses
The resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
widgetsThe tiles on this dashboard, as a list of {widget_id, type, x, y, width, height, settings}. widget_id is yours to choose and must be unique here; type is a dashboard_widget_types id; the geometry is in a 12-column grid whose rows go on for as long as you need. Sent whole: an Update replaces the layout rather than merging tile by tile.
layout_versionThe shape the stored layout is in. The platform raises it when it migrates a dashboard saved by an older release; a client reads it and never sends it.
is_defaultTrue while nobody has ever saved a dashboard for this website and what you are reading is the platform's default layout. It comes with no etag and no timestamps, because there is nothing to be a version of yet — so the first Update sends no If-Match and every later one does.
Update dashboard
Saves an arrangement. Send widgets whole — the layout is replaced, not merged tile by tile, because a tile moved out of the way and a tile deleted are indistinguishable in a per-field merge.
Send the etag you read in If-Match and a write that lost a race is refused with ABORTED instead of overwriting somebody else's arrangement; the refusal carries the current dashboard, so a builder can show what it would have overwritten. The first write of a never-arranged dashboard sends none — there is no version yet.
The whole layout is checked, and every refusal names the tile: a type that is not in dashboard_widget_types, a widget_id used twice, geometry outside the 12 columns or outside the type's own min_size/max_size, two tiles covering each other, more than 24 tiles, a second copy of a type that allows only one, and a setting the type does not declare or a value it does not allow.
path Parameters
website_idId of the parent website.
query Parameters
update_maskComma-separated field paths to merge. A field named here and sent as null is cleared; without the mask a null is dropped (§7, §11).
Headers
If-MatchThe etag the client last read. A mismatch is ABORTED (409) with the current resource in the error details (§14).
Update dashboard › Request Body
widgetsThe tiles on this dashboard, as a list of {widget_id, type, x, y, width, height, settings}. widget_id is yours to choose and must be unique here; type is a dashboard_widget_types id; the geometry is in a 12-column grid whose rows go on for as long as you need. Sent whole: an Update replaces the layout rather than merging tile by tile.
Update dashboard › Responses
The updated resource.
nameThe resource name (§5) — the identity of this resource, and the path that addresses it: websites/{website}/cms_pages/{cms_page}. It is the handle to store, not a human label.
create_timeWhen the resource was created (RFC 3339, UTC).
update_timeWhen the resource last changed (RFC 3339, UTC).
etagVersion of the persisted state. Send it back in If-Match on Update or Delete and the write is rejected with ABORTED if anyone else changed the resource meanwhile (§14).
widgetsThe tiles on this dashboard, as a list of {widget_id, type, x, y, width, height, settings}. widget_id is yours to choose and must be unique here; type is a dashboard_widget_types id; the geometry is in a 12-column grid whose rows go on for as long as you need. Sent whole: an Update replaces the layout rather than merging tile by tile.
layout_versionThe shape the stored layout is in. The platform raises it when it migrates a dashboard saved by an older release; a client reads it and never sends it.
is_defaultTrue while nobody has ever saved a dashboard for this website and what you are reading is the platform's default layout. It comes with no etag and no timestamps, because there is nothing to be a version of yet — so the first Update sends no If-Match and every later one does.
Reset (dashboard)
Throws the arrangement away and puts the platform's default layout back. It answers exactly what a read of a never-arranged dashboard answers, is_default: true included, because that is what the website now has.
The default is composed fresh from the catalogue rather than stored, so a dashboard reset today and a website created tomorrow look the same — and both pick up a tile a later release adds. Safe to repeat: resetting an already default dashboard changes nothing.
path Parameters
website_idId of the parent website.
Reset (dashboard) › Request Body optional
Reset (dashboard) › Responses
The affected resource, or the method’s own response object (§10).