Check an Analytics Dashboard Document
POST https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/check
Checks a dashboard document as CreateAnalyticsDashboard would, without saving it: every problem at once, each with a JSON path into the document and a fix.
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
200 — Whether the document passes, and why not
Content-Type: application/json · Schema: AnalyticsDashboardCheck
AnalyticsDashboardCheck fields:
| Field | Type | Required | Description |
|---|---|---|---|
ok | boolean | yes | |
diagnostics | array<AnalyticsDiagnostic> | yes |
AnalyticsDiagnostic fields:
| Field | Type | Required | Description |
|---|---|---|---|
code | string | yes | |
path | array<object> | yes | Where the problem is: a JSON path into the query, or into the chart config. |
message | string | yes | |
fix | string | no | |
suggestions | array<string> | no | The nearest names that exist, for a name that does not. |
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
Content-Type: application/json · Schema: AiErrorResponse
AiErrorResponse fields:
| Field | Type | Required | Description |
|---|---|---|---|
error | string | yes | Error message |
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 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/check' \
-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 — 200
{
"ok": true,
"diagnostics": [
{
"code": "INVALID_QUERY",
"path": [
"string"
],
"message": "string",
"fix": "string",
"suggestions": [
"string"
]
}
]
} 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.