Lay Out an Analytics Dashboard

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

Moves, sizes, renames and deletes a dashboard's blocks as its page's editor does, and moves the dashboard to its next version. It changes no chart, so it checks the layout, the document's limits and its ids, and plans no chart; a block whose saved chart was deleted is kept. A layout that leaves the document as it is is refused as changing nothing. Name the version last read: a dashboard changed since then is refused with VERSION_CONFLICT. Answers the dashboard's read at its next version, as GetAnalyticsDashboard does.

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 no The dashboard's title, trimmed; left out, the dashboard keeps its own.
blocks array<object> yes The page's blocks, top to bottom, as a layout: each content block is `{ kind, id, width? }` naming one of the dashboard's `chart`, `text`, `image`, `controls` or `divider` blocks by its `id`, a chart block with its own `title?` too (the saved chart's title is left alone), and keeps its content; a row is `{ kind, id, height?, items }`, a column `{ kind, id, width, items }`, a section `{ kind, id, title, collapsed?, items }` and a tabs block `{ kind, id, tabs }`, each tab `{ id, title, items }`, their `items` blocks of the layout. A content block left out is deleted, a section or tab with what it holds, and so is each filter whose `scope` then names nothing, from every controls block too. Rows and columns may be new, each with an id of its own; sections, tabs blocks and tabs are the dashboard's. A title is 1 to 200 characters once trimmed.

Responses

200 — The dashboard's read at its next version

Content-Type: application/json · Schema: AnalyticsDashboardRead

AnalyticsDashboardRead 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.
charts array<AnalyticsSavedChart> yes
reach object yes Each filter's id, with the chart blocks it reaches; a `range` on money whose currency is a field lists each chart a `select` over that field reaches, which it filters only once one currency is picked.
crossFilterable object yes Each chart block's id, with the outputs a click on its marks can filter by.
crossReach object yes Each chart block's id, then each output it can filter by, with the other chart blocks a click on that output filters.
ownRange object no Each filter's id, with the chart blocks it leaves keeping their own range, or their own grain: those a block's read reports it `not_reachable` on with `reason: "own_range"`, which `reach` leaves out. Always sent; an older service sent none.
crossOwnRange object no Each chart block's id, then each output it can filter by, with the other chart blocks a click on that output leaves keeping their own range: those a block's read reports it `not_reachable` on with `reason: "own_range"`, which `crossReach` leaves out. Always sent; an older service sent none.
breakdowns object yes Each chart block that can drill, with the fields of its own dataset "Break down by" offers and their labels: categories, never an id, a number, money or a date. None when the dashboard turns detail off; a drill by any other field is refused.
defaultTimes object no Each dataset the charts the caller may read are over, with its default time: the field a `time` filter adds its range on there, on a chart whose first stage keeps no `within` on a field; on any other it replaces each such `within`, on whatever date. Always sent; an older service sent none.
filterTypes object no Each select filter the caller may read, with its field's type, which names its values as a chart names them: a code as words. Always sent; an older service sent none.

AnalyticsSavedChart fields:

FieldTypeRequiredDescription
id string yes
title string yes
description string yes
version integer yes
createdBy string or null yes
createdAt string yes
updatedAt string yes
query object no The chart's query; absent when the caller cannot read every dataset it reads.
chart AnalyticsChartConfig no

AnalyticsChartConfig fields:

FieldTypeRequiredDescription
type string no The chart type; without it, the type the result's shape asks for.
x string no
y object no The measure, or measures sharing one unit, to plot.
series string no A dimension output; each of its values is drawn as its own series.
size string no
value string no
path array<string> no
rows array<string> no
across array<string> no
columns array<string> no
labels object no Display names for outputs, by output name, each at most 200 characters; the model's labels otherwise.
values boolean no
top number no Keep the N largest series, slices or points; at most seven, or ten slices of a pie, whose eighth to tenth are steps of the gray, each named on its slice.
sort string no
highlight object no One series value, drawn in color while the rest are muted.
target number no A goal, in the measure's unit.
axis object no
stack object no Stack the parts end to end, or not; `percent` stacks a bar's parts as shares of its own total, its axis reading 0% to 100%.
smooth boolean no
step boolean no
horizontal boolean no
lines array<string> no
totals boolean no
scale string no
range array<—> no
trend boolean no
period string no The period a number over a time breakdown shows: `whole`, the newest whole period (the default), or `newest`, the newest period, marked partial while it is.
donut boolean no
show string no
bars array<string> no
search boolean no A table's search box, which keeps the rows a cell of which shows the text typed in it, in any case, and counts them.

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}/layout' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 1,
  "title": "Revenue",
  "blocks": [
    {
      "kind": "row",
      "id": "numbers",
      "items": [
        {
          "kind": "chart",
          "id": "net",
          "width": 12
        }
      ]
    },
    {
      "kind": "chart",
      "id": "trend",
      "title": "Net revenue 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": [
    {}
  ],
  "charts": [
    {
      "id": "01H0000000000000000000",
      "title": "string",
      "description": "string",
      "version": 1,
      "createdBy": "string",
      "createdAt": "2026-01-31T12:00:00Z",
      "updatedAt": "2026-01-31T12:00:00Z",
      "query": {},
      "chart": {
        "type": "line",
        "x": "string",
        "y": "string",
        "series": "string",
        "size": "string",
        "value": "string",
        "path": [
          "string"
        ],
        "rows": [
          "string"
        ],
        "across": [
          "string"
        ],
        "columns": [
          "string"
        ],
        "labels": {},
        "values": true
      }
    }
  ],
  "reach": {},
  "crossFilterable": {},
  "crossReach": {}
}

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.