Skip to main content
POST
Import the data object from a dashboard export into a workspace. Omit mode to create a dashboard. Set mode: "replace" to replace the contents of an existing dashboard with the same dashboardId in that workspace. For a deployment workflow and a field-by-field explanation of what changes, see Replace dashboard contents.
Replace mode overwrites the target dashboard’s base metrics, dashboard filters, and layout. It does not merge the export with local edits. Export the target dashboard before replacing it.

Authentication

Use a company-level service token in the Authorization header. The target workspace must belong to the service token’s company. A Data App API key or guest token cannot be used for this operation.

Headers

string
required
Your service token, prefixed with Bearer.
string
required
Set to application/json. Read an exported file and send its data object as importDashboardData in the JSON request body.

Request body

string
required
Existing target workspace name in the service token’s company. The workspace must have a connected datasource or datamart, or a configured multi-datasource or multi-datamart setup.
object
required
The data object from the Export Dashboard API or a UI-exported dashboard file. Use the complete export data, including its metrics and dashboard configuration. Do not send the enclosing export wrapper as this field.Joi validates this field as an object. The import also validates the exported content and requires eligible metrics; an empty object or a payload with no metrics cannot be used to clear a dashboard.
string
Optional. The only accepted value is the exact lowercase string "replace". Omit this field to create a new dashboard; "create", "merge", "append", and "REPLACE" are not accepted values.With "replace", dashboardId is required and must identify an existing dashboard in workspaceName. A missing target returns an import error; replace mode does not create it automatically.
string
External dashboard ID in the target workspace, rather than its internal database UUID.
  • Create: Optional. Sets the new dashboard’s external ID. If omitted, the import generates an ID. If the supplied ID already exists in the target workspace, the request fails with INVALID_DASHBOARD_ID.
  • Replace: Required. Selects the existing target by external ID and workspace. The target keeps its external ID and internal dashboard record.
string
Optional display name. If omitted, the name from the export is used, including in replace mode. To keep the target’s previous name, provide it explicitly.
object[]
Optional schema mappings for the imported SQL and related configuration. Each item requires replaceSchema and targetSchema, both strings. Strings are trimmed and may be empty; further schema-mapping checks run during the import.Schema mappings do not create warehouse tables, migrate data, or configure a new datasource. Verify that the mapped tables and columns exist in the target connection.

Create and replace behavior

Imported metrics receive new IDs. References within the imported dashboard are remapped where supported; integrations, saved client layouts, and schedules that reference previous metric IDs are not automatically migrated. Old metrics still used by another dashboard or scheduled report are preserved; unreferenced old metrics are eligible for cleanup.

Request examples

These examples use the complete JSON file produced by the export API. The cURL examples use jq to extract its data object and build the request.

Response

object
Import result. On success, contains response. Import-stage failures can instead contain error, even when the HTTP status is 200.
object
Successful import details: message, dashboardId, dashboardName, workspaceName, and importSummary.
object
Includes imported and skipped counts and a skippedMetrics array with details for skipped candidates. Review this summary and the resulting dashboard before marking a deployment complete.
object
Import-stage error with a message, and sometimes additional details. Check this field as well as top-level error and the HTTP status.
object
Request-level failure with code and message, such as invalid parameters, service-token context, or workspace resolution.

Errors and recovery

The importer prepares new metrics before detaching the old ones. On a replacement failure it attempts to remove inserted metrics and, if dashboard fields were changed, restore the previous name, filters, layout, grid spacing, and filter layout. These recovery operations can also fail; the operation is not a single database transaction. Check the target after an error before retrying. Send one replacement at a time for a given dashboard. The endpoint does not serialize overlapping replacements or provide a revision check. See the feature guide for client ownership, saved layouts, and schedule limitations.