Create an Analytics Dashboard
POST https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard
Creates a dashboard from its document: its layout tree of blocks, the filters a viewer sets, and its interactions. The document is checked in full first: its layout, each filter's field and default, each saved chart (one of the organization's that the caller may read) and each chart of its own. The new dashboard is at version 1.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
orgId | path | string | yes | Organization ID |
Request Body
Required. Content-Type: application/json · Schema: AnalyticsDashboardDocument
AnalyticsDashboardDocument fields:
| Field | Type | Required | Description |
|---|---|---|---|
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
201 — The new dashboard
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
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' \
-H "Authorization: Bearer $SUGER_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"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 — 201
{
"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.