# 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](https://doc.fours.com/settings/oauth-app/)._

### Request

```bash
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

```json
{
  "ok": true,
  "diagnostics": [
    {
      "code": "INVALID_QUERY",
      "path": [
        "string"
      ],
      "message": "string",
      "fix": "string",
      "suggestions": [
        "string"
      ]
    }
  ]
}
```

### Error — 401

```json
{
  "error": "string"
}
```

---

API reference: https://doc.fours.com/api/
