Skip to Content

Data Retrieval

Import a dashboard

Make a new dashboard in a workspace from an exported dashboard file.

POST
/api/v2/data-app/import-dashboard

Databrain makes the dashboard with its metrics, filters and layout in the workspace you name.

curl --request POST https://api.usedatabrain.com/api/v2/data-app/import-dashboard \  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \  --header "Content-Type: application/json" \  --data "{    \"workspaceName\": \"Customer analytics EU\",    \"dashboardId\": \"sales-overview-eu\",    \"schemaPairs\": [{ \"replaceSchema\": \"public\", \"targetSchema\": \"eu\" }],    \"importDashboardData\": $(cat dashboard-sales-overview.json)  }"

Before you start

  • You have a service token. See Authentication.
  • You have a file from Export a dashboard.
  • The workspace has a datasource or datamart with the tables the metrics use.

Authorization

ServiceToken
headerAuthorizationBearer <token>

A service token. A data app API token is refused.

Body

workspaceNamestringrequired

The workspace to import into.

importDashboardDataobjectrequired

The export file as it is, or only its data

Id of the new dashboard. Default: the exported id plus a time stamp.

Default: <exported externalDashboardId>_<Date.now()>

Name of the new dashboard. Default: the exported name.

schemaPairsobject[]

Schema names to swap in the metrics' SQL: { "replaceSchema": "public", "targetSchema": "eu" }. Fill both or neither.

2 fields in schemaPairs
replaceSchemastringrequired
targetSchemastringrequired
modestring

replace

dryRunboolean

true checks and shows the changes. Leave it out to replace.

Default: false

Required to replace: the version from your dry run.

Shared metrics you agree to change.

Default: []
messagestring

A note, up to 200 characters.

Default: Import (replace)

Response

{  "data": {    "response": {      "message": "Imported Dashboard with 8 metrics",      "dashboardId": "sales-overview-eu",      "dashboardName": "Sales overview",      "workspaceName": "Customer analytics EU",      "importSummary": {        "imported": 8,        "skipped": 1,        "skippedMetrics": [{ "metricId": "...", "name": "Churn", "reason": "TARGET_TABLE_NOT_FOUND" }]      }    }  }}

A metric is skipped when the workspace cannot run it. reason says why, with the same values as on Create a customer dashboard embed.

If the import fails part way, you still get 200, with data.error instead of data.response, and part of the dashboard can stay. Check data.error on every call.

{ "data": { "error": { "message": "No data source or data mart is connected!", "hint": "..." } } }

Replace a dashboard in place

Send "mode": "replace" to update an existing dashboard from the file, in a dry run first. It needs dashboard environments on for your organization (Settings > Environments), else 403 FEATURE_NOT_ENABLED.

The response is { "data": { "dashboardId", "version", "changes", "metrics", "checks", "warnings", "dryRun" } }. Any other mode value is ignored, and a normal import runs.

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing or wrong
400WORKSPACE_ID_ERRORNo workspace has this name
400INVALID_DASHBOARD_IDA dashboard in the workspace already has this dashboardId
403AUTHENTICATION_ERRORYou used a data app API token
403FEATURE_NOT_ENABLEDReplace: dashboard environments are off
403FOREIGN_EXPORTReplace: the file is from another organization
404DASHBOARD_NOT_FOUNDReplace: no dashboard has this id
400EXPECTED_VERSION_REQUIREDReplace: run a dry run first and send its version
409LIVE_CHANGEDReplace: the dashboard changed after your dry run
500INTERNAL_SERVER_ERRORThe import failed

For errors that every endpoint returns, see Authentication.

Example Request
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/import-dashboard' \  -H 'Content-Type: application/json' \  -d '{  "workspaceName": "string",  "importDashboardData": {}}'
Example Response
{  "data": {    "dashboardId": "sales-overview",    "version": "...",    "changes": {      "added": 0,      "updated": 2,      "retired": 0,      "unchanged": 5    },    "metrics": [      {        "source": "m1",        "target": "m1",        "action": "updated"      }    ],    "checks": [],    "warnings": [],    "dryRun": true  }}