# dashboards operations

MCP tools and operation permissions for dashboards.

Generated from the shared operation catalog. Use [the JSON catalog](https://bytesmap.com/docs/reference/operations.json) for complete input schemas. Required dependency checks can be stricter than the resource permission listed below.

## dashboard_runtime

Read a dynamic dashboard and its permitted component destinations, draft/publication state and access. Resolves existing dashboard URLs. Does not execute queries or actions.

- **HTTP:** `GET /api/dashboards/:id/runtime`
- **SDK:** `client.dashboards.runtime(input)`
- **Access:** workspace; workspace / list
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `id` | Required | string |

## dashboard_list

List accessible dynamic dashboards and folders, with each dashboard's folderId, home layout, parameters and runtime access. Call dashboard_runtime for component destinations and publication, or dashboard_read for the home layout and charts.

- **HTTP:** `GET /api/dashboards`
- **SDK:** `client.dashboards.list(input)`
- **Access:** workspace; dashboard / read
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | string |

## dashboard_folder_create

Create a folder for organizing dashboards. Use dashboard_move to place existing dashboards in it, or folderId when creating a dashboard.

- **HTTP:** `POST /api/dashboards/folders`
- **SDK:** `client.dashboards.createFolder(input)`
- **Access:** workspace; folder / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | See schema |
| `name` | Required | string |

## dashboard_folder_rename

Rename a dashboard folder. Dashboard contents and access remain unchanged.

- **HTTP:** `PATCH /api/dashboards/folders/:folderId`
- **SDK:** `client.dashboards.renameFolder(input)`
- **Access:** workspace; folder / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | See schema |
| `name` | Required | string |
| `folderId` | Required | string |

## dashboard_folder_remove

Remove a folder and return its dashboards to the root library. Does not delete dashboards, charts or queries.

- **HTTP:** `DELETE /api/dashboards/folders/:folderId`
- **SDK:** `client.dashboards.removeFolder(input)`
- **Access:** workspace; folder / admin
- **Effect annotation:** May change state or run effects; destructive operation

| Input | Requirement | Description |
| --- | --- | --- |
| `folderId` | Required | string |

## dashboard_move

Move dashboards into a folder, or pass folderId: null to return them to the root library. Requires write access to every selected dashboard. Moves the whole selection together without changing chart layouts.

- **HTTP:** `POST /api/dashboards/move`
- **SDK:** `client.dashboards.move(input)`
- **Access:** workspace; dashboard / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `ids` | Required | array |
| `folderId` | Required | See schema |

## dashboard_create

Create a dynamic dashboard with an empty home or a layout of saved charts and interactive panels on a 12-column grid ({chart, w, h} or {app, w, h}). Params declared here bind into every chart on the page, so one date control filters all of them. Optionally set folderId to organize it in a folder.

- **HTTP:** `POST /api/dashboards`
- **SDK:** `client.dashboards.create(input)`
- **Access:** workspace; dashboard / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | See schema |
| `title` | Required | string |
| `folderId` | Optional | See schema |
| `description` | Optional | string |
| `layout` | Optional | array |
| `params` | Optional | object |

## dashboard_home_read

Read this workspace's home overview, or the selected project's overview, with its layout, charts and queries resolved. Returns `dashboard: null` if nobody has set one up yet; call dashboard_home_ensure to create it.

- **HTTP:** `GET /api/dashboards/home`
- **SDK:** `client.dashboards.home(input)`
- **Access:** workspace; dashboard / read
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | string |

## dashboard_home_ensure

Create this workspace's home overview, or the selected project's overview, if it does not exist yet. Safe to call repeatedly. Then use dashboard_update with the returned id to place charts on it.

- **HTTP:** `POST /api/dashboards/home`
- **SDK:** `client.dashboards.ensureHome(input)`
- **Access:** workspace; dashboard / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `projectId` | Optional | See schema |

## dashboard_read

Read a dashboard with its layout, its charts and the query behind each one — everything needed to render it, in one call.

- **HTTP:** `GET /api/dashboards/:id`
- **SDK:** `client.dashboards.get(input)`
- **Access:** workspace; dashboard / read
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `id` | Required | string |

## dashboard_cost

Estimate database work for one dashboard refresh without running its queries. Shared saved queries are counted once; costs are grouped by source. PostgreSQL only; unsupported queries remain explicitly unestimated.

- **HTTP:** `POST /api/dashboards/:id/cost`
- **SDK:** `client.dashboards.estimate(input)`
- **Access:** workspace; dashboard / read
- **Effect annotation:** Read-only

| Input | Requirement | Description |
| --- | --- | --- |
| `params` | Optional | object |
| `id` | Required | string |

## dashboard_update

Rename a dashboard or change its layout. Send the whole `layout` array — it replaces the stored one, so read the dashboard first if you are adding to it. Set folderId to move it; null returns it to the root library.

- **HTTP:** `PATCH /api/dashboards/:id`
- **SDK:** `client.dashboards.update(input)`
- **Access:** workspace; dashboard / write
- **Effect annotation:** May change state or run effects

| Input | Requirement | Description |
| --- | --- | --- |
| `title` | Optional | string |
| `folderId` | Optional | See schema |
| `description` | Optional | string |
| `layout` | Optional | array |
| `params` | Optional | object |
| `id` | Required | string |

## dashboard_delete

Delete a dashboard and its layout. Requires dashboard Admin. Read the dashboard and its runtime references first; separately saved charts, queries and source records are retained.

- **HTTP:** `DELETE /api/dashboards/:id`
- **SDK:** `client.dashboards.remove(input)`
- **Access:** workspace; dashboard / admin
- **Effect annotation:** May change state or run effects; destructive operation

| Input | Requirement | Description |
| --- | --- | --- |
| `id` | Required | string |