Update an Analytics Dashboard

PUT https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}

Replaces a dashboard's document with the one given, checked as CreateAnalyticsDashboard checks it, and moves the dashboard to its next version; a document that is the one saved is refused as changing nothing. A block whose saved chart was deleted is refused, with a diagnostic saying to remove it. Name the version last read: a dashboard changed since then is refused with VERSION_CONFLICT.

Parameters

NameInTypeRequiredDescription
orgId path string yes Organization ID
dashboardId path string yes

Request Body

Required. Content-Type: application/json · Schema: object

Request body fields:

FieldTypeRequiredDescription
version integer yes The version the caller last read; a write at any other version is refused with VERSION_CONFLICT.
title string yes
description string no
filters array<object> yes The inputs a viewer sets, each `{ id, label, kind, default?, scope? }` with an id of lower-case letters, digits and `_`: `time` (the dashboard's range; `required?`; `default` as `{ last: 12, unit: "month" }`, moved back by `before` as a chart's `within` is, or `{ past: "year" }`, the year up to the start of today), `grain` (the unit trends are broken down by; `default` as `"month"`), `select` (`field: { dataset, path }`, `multiple?`, `required?`; `default` a list of values, null for none), `range` (`field` of a number, money or date; `default: { low?, high? }`) or `search` (`field` of text). A filter reaches every chart whose dataset has its field, or only the blocks its `scope` lists; with no `default` it starts unset. A `required` time or select is always applied: it has a `default`, and a state that clears it is refused. A `range` on money whose currency is a field reaches a chart only once one currency is picked: a `select` over that field set to one value, or the chart's own first stage keeping that field to one currency. Elsewhere the chart reports it `not_reachable`, though `reach` lists it wherever a `select` over that field reaches it, as the page sends it the range.
blocks array<object> yes The page, top to bottom, as a tree of blocks. Each has an `id` (a lower-case letter, then lower-case letters, digits, `_` or `-`; unique in the dashboard) and a `kind`: `row` (`items` side by side, each with a `width` in columns of 12), `column` (inside a row: a `width` and stacked `items`), `section` (a `title` and `items`), `tabs` (`tabs: [{ id, title, items }]`), `divider`, `chart` (a saved chart's `chartId`, or a `title` and a `query` with an optional `chart` config), `text` (`markdown`), `image` (`src: { url }` on https, and `alt`) or `controls` (`filters`: the ids of the filters whose inputs sit there).
interactions object no `crossFilter`: a click on a mark filters the other charts. `detail`: a mark's rows can be shown, and its chart broken down by another field. Both on when absent.

Responses

200 — The dashboard at its next version

Content-Type: application/json · Schema: AnalyticsDashboard

AnalyticsDashboard fields:

FieldTypeRequiredDescription
id string yes
title string yes
description string no
version integer yes
createdBy string or null yes
createdAt string yes
updatedAt string yes
builtin string no The built-in dashboard Analytics setup added this one as, such as `suger-finance-view`; absent on every other. Only setup sets it: a create or an update naming it is refused, and an update keeps it.
filters array<AnalyticsDashboardReadFilter> yes
blocks array<AnalyticsDashboardReadBlock> yes
interactions object no `crossFilter`: a click on a mark filters the other charts. `detail`: a mark's rows can be shown, and its chart broken down by another field. Both on when absent.

401 — No valid token

Content-Type: application/json · Schema: AiErrorResponse

AiErrorResponse fields:

FieldTypeRequiredDescription
error string yes Error message

403 — Not a member of the organization, a role that cannot write, or DATASET_FORBIDDEN: the query reads a dataset the caller may not read

Content-Type: application/json

404 — NOT_FOUND

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

409 — VERSION_CONFLICT

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

413 — INVALID_REQUEST: the body is larger than 256 KiB

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

422 — INVALID_REQUEST: the document is refused, with a diagnostic per problem, or the body is not valid

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

500 — ANALYTICS_UNAVAILABLE: an unexpected failure

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

503 — ANALYTICS_UNAVAILABLE: analytics is not configured or not ready

Content-Type: application/json · Schema: AnalyticsError

AnalyticsError fields:

FieldTypeRequiredDescription
error object yes

Example

The request bodies are this operation's documented examples; the response and error bodies are generated from its schema. Substitute your own ids, and set SUGER_TOKEN to a bearer token from the OAuth client-credentials exchange.

Request

curl -X PUT 'https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 1,
  "title": "Revenue",
  "description": "Revenue at a glance.",
  "filters": [
    {
      "id": "time",
      "label": "Time",
      "kind": "time",
      "default": {
        "last": 12,
        "unit": "month"
      }
    },
    {
      "id": "partner",
      "label": "Partner",
      "kind": "select",
      "field": {
        "dataset": "revenue",
        "path": [
          "partner"
        ]
      },
      "multiple": true
    }
  ],
  "blocks": [
    {
      "kind": "row",
      "id": "numbers",
      "items": [
        {
          "kind": "chart",
          "id": "net",
          "chartId": "8c0f3a52-5d1e-4f0a-9b7e-2d6c4a1e9f30"
        }
      ]
    },
    {
      "kind": "chart",
      "id": "trend",
      "title": "Net revenue by month",
      "query": {
        "v": 1,
        "from": {
          "dataset": "revenue"
        },
        "stages": [
          {
            "kind": "aggregate",
            "where": {
              "op": "within",
              "arg": {
                "op": "field",
                "path": [
                  "invoice_date"
                ]
              },
              "range": {
                "last": 12,
                "unit": "month"
              }
            },
            "group": {
              "month": {
                "op": "trunc",
                "arg": {
                  "op": "field",
                  "path": [
                    "invoice_date"
                  ]
                },
                "unit": "month"
              },
              "currency": {
                "op": "field",
                "path": [
                  "currency"
                ]
              }
            },
            "measures": {
              "net_revenue": {
                "op": "measure",
                "name": "net_revenue"
              }
            },
            "order": [
              {
                "by": "month"
              }
            ]
          }
        ]
      }
    }
  ]
}'

Response — 200

{
  "id": "01H0000000000000000000",
  "title": "string",
  "version": 1,
  "createdBy": "string",
  "createdAt": "2026-01-31T12:00:00Z",
  "updatedAt": "2026-01-31T12:00:00Z",
  "filters": [
    {}
  ],
  "blocks": [
    {}
  ],
  "description": "string",
  "builtin": "string",
  "interactions": {
    "crossFilter": true,
    "detail": true
  }
}

Error — 401

{
  "error": "string"
}

View as Markdown · API reference overview

Spotted something wrong or out of date on this page? Tell us and we'll correct it.