Update a Saved Analytics Chart

PUT https://api.suger.cloud/ai/org/{orgId}/analytics/chart/{chartId}

Changes a chart's title, description, query or chart config, and moves it to its next version; an update that changes none of them is refused. A new query is checked with the chart's config, and a new config with its query; a `chart` of null goes back to drawing the result as its shape asks. Name the version last read: a chart changed since then is refused with VERSION_CONFLICT. A chart config's `axis` is `{ zero, log, min, max }`, each optional, for the value axis: whether it includes zero (it does unless it is logarithmic), whether it is logarithmic, and where it starts and ends, `min` below `max` and both above zero on a log axis.

Parameters

NameInTypeRequiredDescription
orgId path string yes Organization ID
chartId 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
description string no
query object no An analytics query, in the grammar GetAnalyticsQueryGrammar gives, naming only the datasets ListAnalyticsDatasets lists and the fields, measures and segments GetAnalyticsDataset lists.
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.

Responses

200 — The chart at its next version

Content-Type: application/json · Schema: AnalyticsSavedChart

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 — QUERY_REJECTED, with diagnostics, or INVALID_REQUEST

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/chart/{chartId}' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 1,
  "title": "Net revenue by month, by currency"
}'

Response — 200

{
  "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
  }
}

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.