# Update an Analytics Dashboard

`PUT https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}`

Replaces a dashboard's document with the one given, checked as CreateAnalyticsDashboard checks it, and moves the dashboard to its next version; a document that is the one saved is refused as changing nothing. A block whose saved chart was deleted is refused, with a diagnostic saying to remove it. Name the version last read: a dashboard changed since then is refused with VERSION_CONFLICT.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | path | string | yes | Organization ID |
| `dashboardId` | path | string | yes |  |

## Request Body

Required.

Content-Type: `application/json` · Schema: `object`

**`Request body`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | integer | yes | The version the caller last read; a write at any other version is refused with VERSION_CONFLICT. |
| `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 — The dashboard at its next version

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`

### 404 — NOT_FOUND

Content-Type: `application/json` · Schema: `AnalyticsError`

**`AnalyticsError`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes |  |

### 409 — VERSION_CONFLICT

Content-Type: `application/json` · Schema: `AnalyticsError`

**`AnalyticsError`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes |  |

### 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 PUT 'https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 1,
  "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
{
  "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/
