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

NameInTypeRequiredDescription
orgId path string yes Organization ID

Request Body

Required. Content-Type: application/json · Schema: AnalyticsDashboardDocument

AnalyticsDashboardDocument fields:

FieldTypeRequiredDescription
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:

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

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' \
  -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.