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
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
dashboardId | path | string | yes |
Request Body
Required. Content-Type: application/json · Schema: object
Request body fields:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
409 — VERSION_CONFLICT
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
413 — INVALID_REQUEST: the body is larger than 256 KiB
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
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:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
500 — ANALYTICS_UNAVAILABLE: an unexpected failure
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | object | yes |
503 — ANALYTICS_UNAVAILABLE: analytics is not configured or not ready
Content-Type: application/json · Schema: AnalyticsError
AnalyticsError fields:
| Field | Type | Required | Description |
|---|---|---|---|
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.