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

# Replace dashboard contents

> Deploy an exported dashboard revision to an existing dashboard ID, with replacement rules for metrics, filters, layout, and saved references.

Use replace mode when your application needs to deploy a revised dashboard to an existing dashboard ID. For example, you can maintain an operations dashboard in staging, export the approved revision, and replace the production dashboard's contents without creating a new dashboard record.

Call the [Import Dashboard API](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/import-dashboard.md) with `mode: "replace"`, the target `workspaceName`, the target external `dashboardId`, and the export's `data` object as `importDashboardData`.

> [!WARNING]
>
> Replacement overwrites the dashboard's base metrics, dashboard filters, and layout. Local changes to those parts of the target are replaced by the imported version. Export the target first so you have a recovery copy.

## What changes

| Part of the target | Replacement behavior |
| - | - |
| Dashboard identity | Keeps the existing internal dashboard record and external dashboard ID in the target workspace. |
| Metric cards and elements | Imports new metric records and detaches the previous metrics from this dashboard. Previous metric IDs are not reused. |
| Metric configuration and saved metric filters | Comes from the imported metric definitions, including chart configuration and saved RLS/filter settings. Target metric edits are not merged into the imported records. |
| Dashboard filters | Replaced by the imported filter configuration. Metric-specific filter references are remapped to the new metrics. An export with no dashboard filters clears the target's base filters. |
| Base dashboard layout | Rebuilt from the imported layout with references to the new metrics. Missing exported metric-card positions can be added by the importer. |
| Display name | Uses `dashboardName` when supplied; otherwise uses the exported name. Supply the current name explicitly if you want to keep it. |
| Grid spacing and filter layout | Applies exported `gridMargin` and `dashboardFiltersLayout` when present. Omitting either field preserves that target field. |
| Previous metrics used elsewhere | Preserved if another dashboard or a scheduled report still references them. Unreferenced previous metrics are eligible for deletion. |
| Other target settings | This mode does not replace target ownership, embed access settings, or saved client-specific layout records. |

Replacing a dashboard does not update every client dashboard that was previously copied from it. Each target is a separate import operation.

## Before you start

You need:

* A company-level [service token](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/create-service-token.md), stored on your backend.
* An existing target dashboard and its external dashboard ID in the target workspace.
* A target workspace in the token's company, connected to the intended datasource or datamart.
* A complete dashboard export with eligible metrics and their dependencies.

To create a dashboard for the first time, use the import endpoint with `mode` omitted. The only supported explicit mode value is lowercase `"replace"`; there is no `"create"`, `"merge"`, or `"append"` value.

## Deploy a dashboard revision

**1. Export the source revision and back up the target**

Use the [Export Dashboard API](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/export-dashboard.md) to save both the revised source and the current target as separate JSON files. Keep the source revision file with your application release.

Exported files contain metadata and a `data` object. The import request uses the `data` object. If you export a client-specific view with `sourceClientId`, review the exported metrics and layout before using it as a replacement source.

**2. Prepare the replacement request**

Set `dashboardId` to the existing target's external ID, not the source dashboard's ID or an internal UUID. The API resolves the target within `workspaceName`.

This example reads a complete export file using `jq`:

```bash theme={"dark"}
jq '{
  workspaceName: "Production Analytics",
  dashboardId: "operations-dashboard",
  mode: "replace",
  importDashboardData: .data
}' dashboard-release.json > replace-request.json
```

If the target uses different schema names, add `schemaPairs` to the request. Schema mapping rewrites imported references; it does not create tables or migrate warehouse data.

**3. Replace the target from your backend**

Send the request with your service token:

```bash theme={"dark"}
curl --request POST \
  --url 'https://api.usedatabrain.com/api/v2/data-app/import-dashboard' \
  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @replace-request.json
```

Submit replacements sequentially for each target dashboard. A missing target returns an error; replace mode does not create one automatically.

**4. Check the import result and the dashboard**

Require `data.response` in the response. Check top-level `error` and `data.error`: an import-stage error can arrive with HTTP `200`. Review `data.response.importSummary` for skipped metrics.

Open the target and verify its metric list, dashboard filters, saved metric filters, layout, and query results. Check merged cards, summary or expression cards, and chart-click actions if your dashboard uses them. Refresh integrations that cache metric IDs or filter definitions.

## Limits and recovery

### Full content replacement

The import replaces the base content rather than applying a partial update. It does not append metrics to the existing set or preserve local filter and layout edits. A payload with no eligible metrics returns an error; this feature is not a way to empty a dashboard.

### Metric IDs, saved layouts, and scheduled reports

Imported metrics receive new IDs even when the same export is imported again. References inside the imported configuration are remapped where supported, but saved client-specific layouts, existing schedules, and external integrations are not migrated to the new metric IDs.

Scheduled reports referencing old metrics keep those metrics alive and can continue to use the previous definitions. Review report configuration separately. Saved client layouts can still contain old metric references; verify the dashboard from the affected client views as well as the base view.

### Client ownership

This workspace endpoint does not accept a destination `clientId` or cross-client import controls and does not derive metric ownership from the replacement target. Replacement preserves the target's existing ownership fields, while imported metric ownership can come from the export. It is not a cross-client rebinding operation.

Use a workspace-authored dashboard and source export for a base-dashboard release workflow. If you need to provision a new client dashboard and bind imported metrics to a destination client, use [Create Dashboard Embed](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/create-dashboard-embed.md). Replacing a client-owned target with another client's export can leave the imported metrics unavailable to the intended viewer.

### Concurrency and failed imports

The endpoint does not provide a per-dashboard lock or revision check. Two replacements running at once can leave mixed metric associations or overwrite each other's dashboard fields. Coordinate replacements in your application so only one runs at a time for each target.

New metrics are prepared before old links are removed. On a failed replacement, the importer attempts to remove newly inserted metrics and restore changed dashboard fields. Recovery and orphan cleanup are best-effort operations, rather than one database transaction. After an error, inspect the target before retrying. Keep your export backup; reimporting it also creates new metric IDs and does not restore external references to the original metrics.

## Related

* [Import Dashboard API](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/import-dashboard.md)
* [Export Dashboard API](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/export-dashboard.md)
* [Import and export dashboards in the UI](https://docs.usedatabrain.com/guides/dashboards/import-export-dashboard.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.