Use the Speak AI MCP server tool update_dashboard to update a dashboard.
What does it do?
Update a dashboard. Two modes. (1) Metadata-only: pass just
icon/assignTo/filters/isDefault/settings, with no spec fields and no revision,
except that saving settings.profiles also needs the revision from get_dashboard
(a stale one returns a 409). (2) Spec update: pass the FULL spec (title, source,
dateRange, sections, widgets) plus revision. Widgets and sections are REPLACED,
not merged, so call get_dashboard first and resend everything you want to keep.
revision is the optimistic-concurrency token from
get_dashboard/list_dashboards: the server accepts the write only if it still
matches, then increments it. A 409 conflict means another writer saved first:
re-fetch with get_dashboard, rebuild your changes on the fresh spec, and retry
with the new revision. If settings.feedback.sheetWebhookUrl is set, each Feedback
submission made on the shared dashboard is posted to that external Google Apps
Script URL. Shared dashboard links cache widget data, so field and media edits can
take up to about 5 minutes to show for date ranges that include today (15 at most)
and up to about 17 minutes for past ranges (60 at most); any dashboard update
refreshes it at once. Viewer settings (the settings input): Do not pass settings
unless the user explicitly asks to change this dashboard’s viewer settings. Saving
fields, feedback or fieldEdits moves that dashboard onto the settings flow
immediately: its media pages use these groups and this Feedback setup from then on.
Each section (fields, feedback, fieldEdits, labels, comments, profiles) replaces
that whole section when sent; a section left out keeps its saved value. Call
get_dashboard first and resend every key of the section you change; a key left out
resets to its default. Get field ids from list_fields. Ids that are not the
company’s fields are dropped when saving and returned in droppedFieldIds. When
feedback.isEnabled is true, pass a non-empty feedback.fieldIds (score fields) rather
than leaving it empty. Only set feedback.sheetWebhookUrl when the user gives the
Apps Script URL. fieldEdits.fieldIds may list only fields that have allowed values
(the server rejects any other field with a 400) and that the dashboard’s media pages
show; pass an empty fieldIds to turn field editing off. Labels and comments on the
shared link are off until the user asks to turn them on. Mode ‘apply’ (labels) or
‘reply’ (comments) lets a link viewer write as one of the dashboard’s feedback
submitter names (feedback.submitters, even while feedback itself is off), or as
another typed name only when feedback.allowOtherSubmitter is true. Anyone holding
the share link can pick any of those names, because the link has no sign-in (an
accepted risk; every entry is marked as made via this dashboard), so confirm the
names with the user before saving a write mode. With no submitter names nobody can
write. Label groups that are not active refuse the whole save with a 400 rather than
being dropped. Saving only settings.profiles does not move media pages onto the
settings flow. settings.profiles is a list of up to 5 groups, one per custom field
(a field may appear only once), each with a label (for example Speakers or Products)
and entries that give a value of that field a name, image, description and link.
Entry names must equal that field’s values (trim, case-insensitive), and a name or
id listed twice in a group is rejected with a 400; they are matched by display
string, so renaming a value in the media fields orphans its profile. Names,
descriptions, links and images are PUBLIC to anyone with the dashboard link: write
plain text only, no HTML, and confirm the descriptions and links with the user
before saving. This MCP cannot upload images: leave imageKey out, or pass one copied
unchanged from get_dashboard. To add an image over the API, POST it (multipart,
JPEG/PNG/WEBP/GIF, max 2 MB) to /v1/dashboards/:dashboardId/profile-image and use
the returned imageKey.
Parameters
update_dashboard takes 13 parameters, 1 of them required.
| Name | Type | Required | Description |
|---|---|---|---|
dashboardId |
string | Yes | Dashboard business id |
title |
string | No | Dashboard name: required (with revision) when updating the spec |
revision |
number | No | The revision loaded from get_dashboard. Required for spec updates and for saving settings.profiles; mismatch returns a 409 conflict. |
description |
string | No | Dashboard description, max 280 chars |
source |
object | No | Data source: {type:“folders”, folderIds:[…]} | {type:“team”} | {type:“workspace”} |
dateRange |
object | No | Date range: strict preset only, no free-form start/end dates |
sections |
array of object | No | Optional named widget groups (tabs). Each references widgets by their explicit ids; widgets in no section form the implicit Overview group. |
widgets |
array of object | No | Widgets to place on the dashboard, in order (max 24). The MCP assigns ids and computes a tidy two-per-row grid layout matching the Speak UI unless you pass explicit id/layout. |
icon |
string | No | Icon identifier |
assignTo |
array of string | No | User ids, or group ids in the “<groupId> (G)” convention, to share view access with |
filters |
object | No | Fixed pre-filter applied to every widget on the dashboard (not a filter bar viewers can change). filters.filterList is an array of { fieldName: field id, fieldOperator: “include”, fieldValue: string[] (1 or more), fieldCondition? }; a media file shows only when that field holds one of the values. Shared links apply include filters only. Other keys pass through but only filterList is enforced. |
isDefault |
boolean | No | Make this the owner’s default dashboard. Setting true clears the default flag on the owner’s other dashboards |
settings |
object | No | Viewer settings for media pages opened from this dashboard’s share link: which fields show, how the Fields tab groups them, the Feedback button, which fields Feedback submitters may edit, labels and comments with the reviewer names (feedback submitters) who may write them, and profile groups. Do not pass settings unless the user explicitly asks to change this dashboard’s viewer settings. Saving fields, feedback or fieldEdits moves that dashboard onto the settings flow immediately: its media pages use these groups and this Feedback setup from then on. Each section (fields, feedback, fieldEdits, labels, comments, profiles) replaces that whole section when sent; a section left out keeps its saved value. Call get_dashboard first and resend every key of the section you change; a key left out resets to its default. Get field ids from list_fields. Ids that are not the company’s fields are dropped when saving and returned in droppedFieldIds. When feedback.isEnabled is true, pass a non-empty feedback.fieldIds (score fields) rather than leaving it empty. Only set feedback.sheetWebhookUrl when the user gives the Apps Script URL. fieldEdits.fieldIds may list only fields that have allowed values (the server rejects any other field with a 400) and that the dashboard’s media pages show; pass an empty fieldIds to turn field editing off. Labels and comments on the shared link are off until the user asks to turn them on. Mode ‘apply’ (labels) or ‘reply’ (comments) lets a link viewer write as one of the dashboard’s feedback submitter names (feedback.submitters, even while feedback itself is off), or as another typed name only when feedback.allowOtherSubmitter is true. Anyone holding the share link can pick any of those names, because the link has no sign-in (an accepted risk; every entry is marked as made via this dashboard), so confirm the names with the user before saving a write mode. With no submitter names nobody can write. Label groups that are not active refuse the whole save with a 400 rather than being dropped. Saving only settings.profiles does not move media pages onto the settings flow. settings.profiles is a list of up to 5 groups, one per custom field (a field may appear only once), each with a label (for example Speakers or Products) and entries that give a value of that field a name, image, description and link. Entry names must equal that field’s values (trim, case-insensitive), and a name or id listed twice in a group is rejected with a 400; they are matched by display string, so renaming a value in the media fields orphans its profile. Names, descriptions, links and images are PUBLIC to anyone with the dashboard link: write plain text only, no HTML, and confirm the descriptions and links with the user before saving. This MCP cannot upload images: leave imageKey out, or pass one copied unchanged from get_dashboard. To add an image over the API, POST it (multipart, JPEG/PNG/WEBP/GIF, max 2 MB) to /v1/dashboards/:dashboardId/profile-image and use the returned imageKey. |
Behaviour
The Speak AI MCP server publishes these behaviour hints for update_dashboard.
- Can change data in your workspace.
- Can delete or overwrite data. Use with care.
- Repeating an identical call can have an extra effect.
- Can reach systems outside Speak AI.
Related
- Dashboards lists the rest of the Dashboards category.
- Tool reference lists every Speak AI MCP server tool.
- MCP server covers setup, supported clients, and what agents can do once connected.