# Add a saved chart to an analytics dashboard

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

Places a saved chart of the organization on a dashboard as a block of the full width, at `position` among the top-level blocks or last, and moves the dashboard to its next version. 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. |
| `chartId` | string | yes |  |
| `position` | integer | no | Where among the top-level blocks to place the chart, from 0; last 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 POST 'https://api.suger.cloud/ai/org/{orgId}/analytics/dashboard/{dashboardId}/chart' \
  -H "Authorization: Bearer $SUGER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "version": 1,
  "chartId": "8c0f3a52-5d1e-4f0a-9b7e-2d6c4a1e9f30",
  "position": 0
}'
```

### 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/
