Reference / Publishing

update_dashboard

Rename a dashboard or edit its metadata without republishing it. Parameters, the rename pipeline, errors and scope rules.

Changes a dashboard's metadata, renames it, or both, without republishing it. A rename leaves the old URL working as a 301 redirect to the new canonical one. To replace the body, use publish_dashboard instead.

When you combine new_slug with metadata fields, both apply atomically.

Behaviour hints for clients: not read-only, idempotent, not open-world.

Parameters

Parameter	Type	Required	Notes
`slug`	string	yes	The dashboard's current canonical slug.
`new_slug`	string	no	Rename target. Must differ from `slug` and not collide with another slug or alias of yours.
`name`	string	no	Display name. Omit to preserve. Empty string is rejected.
`tags`	array	no	Omit to preserve, `[]` to clear.
`chart`	string	no	Omit to preserve. Empty string is rejected.
`workspace`	string	no	Workspace slug.

At least one of new_slug, name, tags or chart must be provided.

The display name follows the URL by default

Passing new_slug without name auto-sets the name to the title-cased form of the new slug, so quarterly-revenue becomes Quarterly Revenue. Pass name explicitly to keep a custom label through a rename.

Returns

A rename:

Updated workspace dashboard.
Renamed: marketing-dashboard -> quarterly-revenue
Name: Quarterly Revenue
Chart: bar
Tags: marketing, q2
URL: https://acme.dashies.ai/quarterly-revenue

A metadata-only edit reports the current state, and carries Slug where the rename carries Renamed:

Updated workspace dashboard.
Slug: quarterly-revenue
Name: Quarterly Revenue
URL: https://acme.dashies.ai/quarterly-revenue

Chart and Tags belong to the RENAME shape, where they appear only when set. The metadata shape is exactly the block above it and never carries either, whatever the dashboard has. The trailing URL line is appended by the tool rather than built by the update itself, so it is the last line of both.

There is no OLD-URL line. A rename leaves the previous slug as an alias that 301s, which URLs, slugs and reserved names covers, but the receipt does not restate it.

Errors

Beyond the shared path and metadata rules:

Condition	Text
`new_slug` not a string	`new_slug must be a string`
`new_slug` fails slug validation	`new_slug invalid: <slug error>`
`new_slug` equals `slug`	`new_slug must differ from slug`
Nothing to change	`at least one of new_slug, name, tags, chart must be provided`
`visibility` passed at all	`visibility is no longer accepted: public dashboards have been removed, so every dashboard is visible to its owner or, for a workspace dashboard, to that workspace's members. Omit the argument.`
The slug names no dashboard, on a metadata-only edit	`dashboard not found for slug "<slug>"`

A metadata-only edit of a slug that does not exist is a not-found rather than a silent create. A RENAME of a missing slug is refused by the database in the same words, and that sentence is one of the permanent patterns, so it arrives inside the rename rejected: <msg> form that Rename failures tell you whether to retry covers.

Rename failures tell you whether to retry

A rename is three steps: reserve the new slug, copy the bytes, then promote atomically. Each failure names where it stopped and whether retrying is safe.

Text	What happened, and what to do
`rename rejected: <msg>`	A permanent refusal such as a collision or a validation failure. Do not retry with the same arguments.
`rename reserve failed (no DB or R2 changes yet - safe to retry): <msg>`	Nothing was touched. Retry.
`r2 copy failed (new_slug "<new>" remains reserved by this dashboard; retry to complete the rename, or pick a different new_slug): <err>`	The name is claimed by this dashboard. Retry to finish, or choose another target to abandon it.
`db rename failed (reservation + R2 already in place; old URL still works - safe to retry): <msg>`	The old URL is still serving. Retry.
`metadata update failed: <msg>`	The metadata-only path failed. Nothing renamed.

Retrying with the same arguments is safe by design: the reservation is idempotent, and a call that succeeded but whose response was lost is detected and returned as success on retry.

A rename invalidates a list cursor

This call bumps the row's updated_at, and list_dashboards paginates on that column. If you are walking pages and rename mid-walk, discard the cursor and restart from a fresh first page, or you will skip the row you just changed.

Scope

The renamed URL is <workspace>.dashies.ai/<new_slug> and the old one 301-redirects.

Check it worked

Load the old URL. It should 301 to the new one rather than 404. Then run list_dashboards and confirm the entry shows the new slug and the name you expected, since a rename without an explicit name rewrites the display name too.