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

### Request

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

```json
{
  "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

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

---

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