# Lay Out an Analytics Dashboard

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

Moves, sizes, renames and deletes a dashboard's blocks as its page's editor does, and moves the dashboard to its next version. It changes no chart, so it checks the layout, the document's limits and its ids, and plans no chart; a block whose saved chart was deleted is kept. A layout that leaves the document as it is is refused as changing nothing. Name the version last read: a dashboard changed since then is refused with VERSION_CONFLICT. Answers the dashboard's read at its next version, as GetAnalyticsDashboard does.

## 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 | no | The dashboard's title, trimmed; left out, the dashboard keeps its own. |
| `blocks` | array<object> | yes | The page's blocks, top to bottom, as a layout: each content block is `{ kind, id, width? }` naming one of the dashboard's `chart`, `text`, `image`, `controls` or `divider` blocks by its `id`, a chart block with its own `title?` too (the saved chart's title is left alone), and keeps its content; a row is `{ kind, id, height?, items }`, a column `{ kind, id, width, items }`, a section `{ kind, id, title, collapsed?, items }` and a tabs block `{ kind, id, tabs }`, each tab `{ id, title, items }`, their `items` blocks of the layout. A content block left out is deleted, a section or tab with what it holds, and so is each filter whose `scope` then names nothing, from every controls block too. Rows and columns may be new, each with an id of its own; sections, tabs blocks and tabs are the dashboard's. A title is 1 to 200 characters once trimmed. |

## Responses

### 200 — The dashboard's read at its next version

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

**`AnalyticsDashboardRead`** 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. |
| `charts` | array<AnalyticsSavedChart> | yes |  |
| `reach` | object | yes | Each filter's id, with the chart blocks it reaches; a `range` on money whose currency is a field lists each chart a `select` over that field reaches, which it filters only once one currency is picked. |
| `crossFilterable` | object | yes | Each chart block's id, with the outputs a click on its marks can filter by. |
| `crossReach` | object | yes | Each chart block's id, then each output it can filter by, with the other chart blocks a click on that output filters. |
| `ownRange` | object | no | Each filter's id, with the chart blocks it leaves keeping their own range, or their own grain: those a block's read reports it `not_reachable` on with `reason: "own_range"`, which `reach` leaves out. Always sent; an older service sent none. |
| `crossOwnRange` | object | no | Each chart block's id, then each output it can filter by, with the other chart blocks a click on that output leaves keeping their own range: those a block's read reports it `not_reachable` on with `reason: "own_range"`, which `crossReach` leaves out. Always sent; an older service sent none. |
| `breakdowns` | object | yes | Each chart block that can drill, with the fields of its own dataset "Break down by" offers and their labels: categories, never an id, a number, money or a date. None when the dashboard turns detail off; a drill by any other field is refused. |
| `defaultTimes` | object | no | Each dataset the charts the caller may read are over, with its default time: the field a `time` filter adds its range on there, on a chart whose first stage keeps no `within` on a field; on any other it replaces each such `within`, on whatever date. Always sent; an older service sent none. |
| `filterTypes` | object | no | Each select filter the caller may read, with its field's type, which names its values as a chart names them: a code as words. Always sent; an older service sent none. |

**`AnalyticsSavedChart`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes |  |
| `title` | string | yes |  |
| `description` | string | yes |  |
| `version` | integer | yes |  |
| `createdBy` | string or null | yes |  |
| `createdAt` | string | yes |  |
| `updatedAt` | string | yes |  |
| `query` | object | no | The chart's query; absent when the caller cannot read every dataset it reads. |
| `chart` | AnalyticsChartConfig | no |  |

**`AnalyticsChartConfig`** fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | no | The chart type; without it, the type the result's shape asks for. |
| `x` | string | no |  |
| `y` | object | no | The measure, or measures sharing one unit, to plot. |
| `series` | string | no | A dimension output; each of its values is drawn as its own series. |
| `size` | string | no |  |
| `value` | string | no |  |
| `path` | array<string> | no |  |
| `rows` | array<string> | no |  |
| `across` | array<string> | no |  |
| `columns` | array<string> | no |  |
| `labels` | object | no | Display names for outputs, by output name, each at most 200 characters; the model's labels otherwise. |
| `values` | boolean | no |  |
| `top` | number | no | Keep the N largest series, slices or points; at most seven, or ten slices of a pie, whose eighth to tenth are steps of the gray, each named on its slice. |
| `sort` | string | no |  |
| `highlight` | object | no | One series value, drawn in color while the rest are muted. |
| `target` | number | no | A goal, in the measure's unit. |
| `axis` | object | no |  |
| `stack` | object | no | Stack the parts end to end, or not; `percent` stacks a bar's parts as shares of its own total, its axis reading 0% to 100%. |
| `smooth` | boolean | no |  |
| `step` | boolean | no |  |
| `horizontal` | boolean | no |  |
| `lines` | array<string> | no |  |
| `totals` | boolean | no |  |
| `scale` | string | no |  |
| `range` | array<—> | no |  |
| `trend` | boolean | no |  |
| `period` | string | no | The period a number over a time breakdown shows: `whole`, the newest whole period (the default), or `newest`, the newest period, marked partial while it is. |
| `donut` | boolean | no |  |
| `show` | string | no |  |
| `bars` | array<string> | no |  |
| `search` | boolean | no | A table's search box, which keeps the rows a cell of which shows the text typed in it, in any case, and counts them. |

### 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}/layout' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 1,
  "title": "Revenue",
  "blocks": [
    {
      "kind": "row",
      "id": "numbers",
      "items": [
        {
          "kind": "chart",
          "id": "net",
          "width": 12
        }
      ]
    },
    {
      "kind": "chart",
      "id": "trend",
      "title": "Net revenue 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": [
    {}
  ],
  "charts": [
    {
      "id": "01H0000000000000000000",
      "title": "string",
      "description": "string",
      "version": 1,
      "createdBy": "string",
      "createdAt": "2026-01-31T12:00:00Z",
      "updatedAt": "2026-01-31T12:00:00Z",
      "query": {},
      "chart": {
        "type": "line",
        "x": "string",
        "y": "string",
        "series": "string",
        "size": "string",
        "value": "string",
        "path": [
          "string"
        ],
        "rows": [
          "string"
        ],
        "across": [
          "string"
        ],
        "columns": [
          "string"
        ],
        "labels": {},
        "values": true
      }
    }
  ],
  "reach": {},
  "crossFilterable": {},
  "crossReach": {}
}
```

### Error — 401

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

---

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