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

# Import Dashboard

> Import a dashboard from a previously exported JSON payload into a workspace.

Import a dashboard into a workspace using JSON data from the [Export Dashboard API](/developer-docs/helpers/api-reference/export-dashboard) or from a file exported via the Databrain UI. The dashboard layout, metrics, and filters are recreated in the target workspace.

<Warning>
  **Authentication Requirement:** This endpoint requires a **service token** (company-level), not a data app API key. The workspace must belong to your company.
</Warning>

## Authentication

Use your service token in the `Authorization` header. See [Create Service Token](/developer-docs/helpers/api-reference/create-service-token) for how to obtain a service token.

<Panel>
  <RequestExample>
    ```bash Authentication theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/data-app/import-dashboard \
      --header 'Authorization: Bearer YOUR_SERVICE_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{"workspaceName":"Target Workspace","importDashboardData":{...}}'
    ```
  </RequestExample>
</Panel>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your **service token** (company-level).

  ```
  Authorization: Bearer dbn_live_...
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<Note>
  Validated with **`importDashboardSchema`**: **`workspaceName`** (string, required) and **`importDashboardData`** (object, required) are required. **`dashboardId`**, **`dashboardName`**, and **`schemaPairs`** are optional. Each **`schemaPairs`** item must include **`replaceSchema`** and **`targetSchema`** (strings).
</Note>

<ParamField body="workspaceName" type="string" required>
  The name of the workspace where the dashboard should be imported. Must match an existing workspace name in your company.
</ParamField>

<ParamField body="importDashboardData" type="object" required>
  The dashboard payload to import. Must be a non-null object. Use the `data` property from an [Export Dashboard](/developer-docs/helpers/api-reference/export-dashboard) response, or the equivalent structure from a UI-exported JSON file. Contains layout, filters, metrics configuration, and related dashboard structure.

  <Expandable title="Getting import data">
    * From **Export Dashboard API**: use the `data` property of the exported JSON.
    * From **UI export file**: use the `data` property from the downloaded JSON file.
  </Expandable>
</ParamField>

<ParamField body="dashboardId" type="string">
  Optional stable identifier for the imported dashboard in the target workspace.

  * If provided, this value is used as the external dashboard ID.
  * If omitted, a new unique ID is generated automatically.
  * If a dashboard with the same ID already exists in the target workspace, the import returns an error message and no new dashboard is created.
</ParamField>

<ParamField body="dashboardName" type="string">
  Optional display name to assign to the imported dashboard in the target workspace.

  If omitted, the name from the exported payload is used.
</ParamField>

<ParamField body="schemaPairs" type="array">
  Optional. Maps schema names in the exported SQL/dashboard payload to schema names in the target workspace (for example when moving from staging to production).

  Each array element is an object with:

  * **`replaceSchema`** — string (required in each item)
  * **`targetSchema`** — string (required in each item)

  ```json theme={"dark"}
  "schemaPairs": [
    { "replaceSchema": "databrain_dev1", "targetSchema": "databrain_dev2" }
  ]
  ```
</ParamField>

## Response

<ResponseField name="data" type="object">
  Result of the import operation.

  On success, `data.response` contains:

  * `message` – human-readable summary of the import (including the number of imported metrics)
  * `dashboardId` – external dashboard ID in the target workspace
  * `dashboardName` – name of the imported dashboard in the target workspace
  * `workspaceName` – name of the workspace where the dashboard was imported
</ResponseField>

On error, the API returns a JSON object with `error.code` and `error.message` and HTTP status 400 or 500.

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request POST \
      --url 'https://api.usedatabrain.com/api/v2/data-app/import-dashboard' \
      --header 'Authorization: Bearer dbn_live_...' \
      --header 'Content-Type: application/json' \
      --data '{
        "workspaceName": "Target Workspace",
        "importDashboardData": {
          "layout": [],
          "filters": [],
          "gridMargin": {}
        },
        "dashboardId": "sales-dashboard-1-copy",
        "dashboardName": "Sales Dashboard (Copy)",
        "schemaPairs": [
          { "replaceSchema": "source_schema", "targetSchema": "public" }
        ]
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    // Assume exportedJson is the object from Export Dashboard API or from reading the exported file
    const exportedJson = { _meta: {...}, data: {...} };
    const importDashboardData = exportedJson.data || exportedJson;

    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/import-dashboard', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer dbn_live_...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        workspaceName: 'Target Workspace',
        importDashboardData,
        dashboardId: 'sales-dashboard-1-copy',
        dashboardName: 'Sales Dashboard (Copy)',
        schemaPairs: [
          { replaceSchema: 'source_schema', targetSchema: 'public' }
        ]
      })
    });

    const result = await response.json();
    if (result.error) {
      throw new Error(result.error.message);
    }
    console.log('Imported:', result.data);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/import-dashboard"
    headers = {
        "Authorization": "Bearer dbn_live_...",
        "Content-Type": "application/json"
    }
    # Use the "data" part of an exported dashboard JSON
    payload = {
        "workspaceName": "Target Workspace",
        "importDashboardData": {
            "layout": [],
            "filters": [],
            "gridMargin": {}
        },
        "dashboardId": "sales-dashboard-1-copy",
        "dashboardName": "Sales Dashboard (Copy)",
        "schemaPairs": [
            {"replaceSchema": "source_schema", "targetSchema": "public"}
        ]
    }

    response = requests.post(url, headers=headers, json=payload)
    data = response.json()

    if "error" in data:
        raise Exception(data["error"].get("message", "Import failed"))
    print("Imported:", data.get("data"))
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success Response theme={"dark"}
    {
      "data": {
        "response": {
          "message": "Imported Dashboard with 10 metrics",
          "dashboardId": "sales-dashboard-1-copy",
          "dashboardName": "Sales Dashboard (Copy)",
          "workspaceName": "Target Workspace"
        }
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"workspaceName\" is required"
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "Invalid Service Token"
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "WORKSPACE_ID_ERROR",
        "message": "invalid workspace name, workspace name not found"
      }
    }
    ```
  </ResponseExample>
</Panel>

## HTTP Status Code Summary

| Status Code | Description                                                                            |
| ----------- | -------------------------------------------------------------------------------------- |
| `200`       | **OK** – Dashboard imported successfully                                               |
| `400`       | **Bad Request** – Invalid or missing parameters, invalid token, or workspace not found |
| `500`       | **Internal Server Error** – Server error during import                                 |

## Possible Errors

| Code                    | Message                                                                                 | HTTP Status |
| ----------------------- | --------------------------------------------------------------------------------------- | ----------- |
| `INVALID_REQUEST_BODY`  | Joi validation message (e.g. `"workspaceName" is required`, invalid `schemaPairs` item) | 400         |
| `AUTHENTICATION_ERROR`  | Invalid Service Token (e.g. missing/invalid company context on token)                   | 400         |
| `WORKSPACE_ID_ERROR`    | invalid workspace name, workspace name not found                                        | 400         |
| `INTERNAL_SERVER_ERROR` | Server error message                                                                    | 500         |

## Related

* [Export Dashboard](/developer-docs/helpers/api-reference/export-dashboard) – Export a dashboard to get the payload for import
* [Import/Export Dashboard (UI)](/guides/dashboards/import-export-dashboard) – UI guide for import/export