Dashboards

Update a dashboard

Update a dashboard. Send only the keys you want to change. To change the dashboard itself, send the full spec with the revision you read: the write is accepted only while it still matches, and returns 409 otherwise. Settings, icon, sharing, filters and the default flag can be changed without a spec.

Viewer settings

settings controls what viewers of the dashboard's share link see on each media page. Each section (fields, feedback, labels, comments, profiles) is saved on its own: the section you send replaces the stored one in full, and a section you leave out keeps its stored value. Read the dashboard first and resend every key of the section you change.

Labels and comments are off until you turn them on. With labels.mode set to apply or comments.mode set to reply, a viewer picks one of the dashboard's feedback submitter names (feedback.submitters, even while feedback itself is off), or types another name when feedback.allowOtherSubmitter is on, and writes under that name. With no names and other names off, nobody can write. The link has no sign-in, so these writes are not authenticated: the link holder chooses the name and Speak AI records the entry under it without checking who sent it, the same as feedback. Only the dashboard's feedback names are accepted, plus any other name when feedback.allowOtherSubmitter is on. Speak AI accepts this risk by design and limits it: every entry written through the link is shown as made via the dashboard, a name can change or delete only the entries written under it from that dashboard, a name that is not allowed is refused on every write, and revoking the link stops every write at once. List only the names you are happy for link holders to write as.

Errors

  • 400 when a field fails validation, the spec is invalid, the payload is too large, or a label group is not an active group of your company ("Choose active label groups from this workspace."). Nothing is saved.
  • 404 when the dashboard does not exist or you cannot edit it.
  • 409 when the spec revision is stale: "Dashboard was modified by another update. Reload and try again."
put/dashboards/{dashboardId}

Request

  • Base URL: https://api.speakai.co/v1
  • URL: https://api.speakai.co/v1/dashboards/{dashboardId}
  • Auth: API key in header x-speakai-key and API key in header x-access-token

Path parameters

dashboardIdstring required

Id of the dashboard, as returned when it was created.

Request body

specobject

The dashboard itself: title (1 to 60 characters), description (up to 280), source ({"type": "workspace"}, {"type": "team"} or {"type": "folders", "folderIds": [...]}), dateRange ({"preset": "last30days"}), sections and widgets. It is checked against the dashboard spec schema, and unknown keys return 400. When sent it must be the full spec, with revision.

revisionnumber

The dashboard's current revision, a whole number. Required when you send settings.profiles without a spec; a stale one returns 409.

iconstring

Icon identifier. Optional. An empty string is allowed.

assignTostring[]

User ids, or group ids written as <groupId> (G), that can view the dashboard. Optional.

filtersobject

Saved filters for the dashboard. Optional. Up to 100 keys; filterList holds up to 20 filters.

isDefaultboolean

Make this your default dashboard. Setting it clears the flag on your other dashboards. Optional.

Response

Success

status'success'

success on every 2xx response.

Changes