> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Programmatic Dashboard Management

> Use the Upsolve API to dynamically create, clone, and manage dashboards and their charts.

## Overview

The Dashboard Management API lets you programmatically control workspaces and dashboards. Common use cases include:

* Building a custom sidebar listing available dashboards
* Dynamically creating dashboards when users enable features (e.g. "Enable revenue charts")
* Cloning template dashboards for new customers
* Bulk-adding or removing charts from dashboards

## Authentication

All Dashboard Management endpoints accept a **user JWT** in the `Authorization` header. This is the same JWT you receive from the [Get Project User Token](/api-reference/endpoint/get-project-user-token) endpoint.

```bash theme={null}
Authorization: Bearer <user_jwt>
```

Alternatively, you can authenticate with an **Upsolve API key** for server-to-server calls:

```bash theme={null}
Authorization: Bearer up_admin_************
```

<Tip>
  User JWT authentication is recommended for frontend iFrame integrations. API
  key authentication is recommended for backend automations.
</Tip>

## Workflow 1: Build a Custom Dashboard Sidebar

List all workspaces, then list dashboards within a workspace to build your own navigation UI.

### Step 1: List Workspaces

```bash theme={null}
curl -X GET "https://api.upsolve.ai/v1/api/dashboard/list-workspaces" \
  -H "Authorization: Bearer up_admin_************"
```

### Step 2: List Dashboards in a Workspace

```bash theme={null}
curl -X GET "https://api.upsolve.ai/v1/api/dashboard/list-workspace-dashboards?workspaceId=<workspace_id>" \
  -H "Authorization: Bearer <user_jwt>"
```

Response:

```json theme={null}
{
  "dashboards": [
    {
      "id": "abc-123",
      "name": "Revenue Overview",
      "tenantId": null,
      "createdAt": "2024-01-15T..."
    },
    {
      "id": "def-456",
      "name": "My Custom View",
      "tenantId": "tenant-789",
      "createdAt": "2024-02-01T..."
    }
  ]
}
```

### Step 3: Render in Your App

Embed the application as an iFrame to render the current user's dashboards, passing their project user token as the `jwt` query parameter:

```tsx theme={null}
<iframe
  src={`https://ai-hub.upsolve.ai/share/application/${applicationId}?jwt=${userJwt}&theme=light`}
  width="100%"
  height="800"
  style={{ border: "none" }}
  title="Embedded Analytics"
/>
```

See [Frontend Setup](/embedded-bi/deploy-dashboards/frontend-setup) for the full iFrame embedding guide.

## Workflow 2: Create a Dashboard and Add Charts

Create a new empty dashboard, then populate it with charts from your chart library.

### Step 1: Create an Empty Dashboard

```bash theme={null}
curl -X POST "https://api.upsolve.ai/v1/api/dashboard/create" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "workspaceId": "<workspace_id>", "name": "My New Dashboard" }'
```

### Step 2: Add Charts

```bash theme={null}
curl -X POST "https://api.upsolve.ai/v1/api/dashboard/add-charts" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetDashboardId": "<new_dashboard_id>",
    "charts": [
      { "chartId": "<revenue_chart_id>" },
      { "chartId": "<cost_chart_id>" },
      { "chartId": "<profit_chart_id>" }
    ]
  }'
```

Charts are deep-copied into the target dashboard, so changes to the originals won't affect the copy.

## Workflow 3: Clone a Dashboard

Clone an existing dashboard (with all its charts) into the same or a different workspace.

```bash theme={null}
curl -X POST "https://api.upsolve.ai/v1/api/dashboard/clone" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDashboardId": "<template_dashboard_id>",
    "targetWorkspaceId": "<target_workspace_id>",
    "name": "Sales Dashboard for ACME Corp"
  }'
```

## Workflow 4: Merge Charts Between Dashboards

Append all charts from one dashboard to another. This is useful for enabling feature bundles (e.g., "Enable revenue charts" adds all revenue-related charts).

```bash theme={null}
curl -X POST "https://api.upsolve.ai/v1/api/dashboard/append-charts-from" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceDashboardId": "<revenue_template_dashboard_id>",
    "targetDashboardId": "<users_dashboard_id>"
  }'
```

## Workflow 5: Remove Charts from a Dashboard

Remove specific charts that are no longer needed:

```bash theme={null}
curl -X POST "https://api.upsolve.ai/v1/api/dashboard/remove-charts" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "<dashboard_id>",
    "chartIds": ["<chart_id_1>", "<chart_id_2>"]
  }'
```

The chart records are preserved in the chart library. Only the dashboard layout is updated.

## API Reference

| Endpoint                                                                       | Description                                   |
| ------------------------------------------------------------------------------ | --------------------------------------------- |
| [List Workspaces](/api-reference/endpoint/list-workspaces)                     | List all workspaces in your organization      |
| [List Workspace Dashboards](/api-reference/endpoint/list-workspace-dashboards) | List dashboards in a workspace                |
| [Create Dashboard](/api-reference/endpoint/create-dashboard)                   | Create a new empty dashboard                  |
| [Clone Dashboard](/api-reference/endpoint/clone-dashboard)                     | Deep-copy a dashboard with all charts         |
| [Add Charts](/api-reference/endpoint/add-charts-to-dashboard)                  | Add charts to a dashboard                     |
| [Remove Charts](/api-reference/endpoint/remove-charts-from-dashboard)          | Remove charts from a dashboard                |
| [Append Charts](/api-reference/endpoint/append-charts-from-dashboard)          | Copy all charts from one dashboard to another |