Add a saved chart to an analytics dashboard

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

Places a saved chart of the organization on a dashboard as a block of the full width, at `position` among the top-level blocks or last, and moves the dashboard to its next version. 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.
chartId string yes
position integer no Where among the top-level blocks to place the chart, from 0; last 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 POST 'https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}/chart' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 1,
  "chartId": "8c0f3a52-5d1e-4f0a-9b7e-2d6c4a1e9f30",
  "position": 0
}'

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.