Skip to Content

Embeds

Create a customer dashboard embed

Make a new dashboard for one customer, from scratch, from a template or from an export, and embed it.

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

Databrain creates a dashboard owned by the customer in clientId, then embeds it in the data app.

curl --request POST https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \  --header "Authorization: Bearer $DATABRAIN_API_TOKEN" \  --header "Content-Type: application/json" \  --data '{    "workspaceName": "Customer analytics",    "dashboardId": "acme-sales",    "clientId": "acme",    "name": "Acme sales",    "templateDashboardId": "sales-overview",    "isImportMetrics": true,    "accessSettings": {      "datamartName": "Sales",      "metricCreationMode": "DRAG_DROP",      "isAllowEmailReports": true,      "isAllowManageMetrics": true,      "isAllowCreateDashboardView": true,      "isAllowMetricCreation": true,      "isAllowMetricDeletion": true,      "isAllowMetricLayoutChange": true,      "isAllowMetricUpdate": true,      "isAllowUnderlyingData": true    }  }'

Before you start

  • You have a data app API token for the data app. See Authentication.
  • Your plan includes embedding.

Authorization

DataAppApiToken
headerAuthorizationBearer <token>

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

Body

Send JSON, or multipart/form-data to upload an export file.

workspaceNamestringrequired

The workspace for the new dashboard.

dashboardIdstringrequired

Id of the new dashboard, also the embed id. No dashboard in the workspace may have it.

clientIdstringrequired

The customer who owns the dashboard. Same value as the guest token's clientId

accessSettingsobjectrequired
19 fields in accessSettings
datamartNamestringrequired

The datamart the embed queries. Its tenancy must match the workspace.

metricCreationModestringrequired

Create metrics with DRAG_DROP or CHAT

isAllowEmailReportsbooleanrequired

Schedule email reports.

isAllowManageMetricsbooleanrequired

Manage metrics.

Save dashboard views.

isAllowMetricCreationbooleanrequired

Create metrics.

isAllowMetricDeletionbooleanrequired

Delete metrics.

Move and resize metrics.

isAllowMetricUpdatebooleanrequired

Edit metrics.

isAllowUnderlyingDatabooleanrequired

See the underlying data.

Use AI features.

Default: false

Add dashboard filters.

Default: false

Add metric filters.

Default: false

Import a dashboard that uses another tenant's metrics, rebound to their own tenant.

Default: false
joinModelstring

multi lets metrics join tables. single does not.

Same as joinModel: multi (older field)

Default: false

The tenant column per table: { "name": "orders", "clientColumn": "customer_id" }. name has no schema.

Default: From the datamart
2 fields in tableTenancySettings
clientColumnstringrequired
namestringrequired

Columns they can filter dashboards on: { "tableName": "public.orders", "columns": ["region"] }

Default: All columns
2 fields in dashboardFilterColumns
tableNamestringrequired
columnsstring[]required

Columns they can filter metrics on, same shape.

Default: All columns
2 fields in metricFilterColumns
tableNamestringrequired
columnsstring[]required
namestring

Embed name. Default: dashboardId

Embed description.

Give the dashboard the name too. Otherwise it is named <dashboardId>_<clientId>

Default: false

A dashboard in the same workspace. Its filters and spacing are copied, not its layout.

Also copy the template's metrics.

METRIC or GALLERY

New metrics are private to the user who makes them. Default false

metadataobject

Your own data, stored on the dashboard and returned by List embeds

A dashboard export, from Export an embedded dashboard or Export a dashboard. Overrides the template.

schemaPairsobject[]

Schema names to swap in imported SQL: { "replaceSchema": "staging", "targetSchema": "public" }

2 fields in schemaPairs
replaceSchemastringrequired
targetSchemastringrequired

Multipart only: the export as a .json file. Overrides importDashboardData

Format: binary

With multipart, send accessSettings, metadata, importDashboardData, schemaPairs and the booleans as JSON strings.

Response

{  "id": "acme-sales",  "name": "Acme sales",  "importSummary": {    "imported": 8,    "skipped": 1,    "skippedMetrics": [      { "metricId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e", "name": "Churn", "reason": "TARGET_TABLE_NOT_FOUND" }    ]  }}

importSummary is there only after an import. A metric can be skipped for TARGET_TABLE_NOT_FOUND, MISSING_DATASET_CONFIGURATION, MISSING_DEPENDENT_METRIC, RAW_SQL_NOT_SAFE_TO_REGENERATE, TARGET_CLIENT_COLUMN_NOT_CONFIGURED or QUERY_GENERATION_FAILED.

Errors

Errors can have hint and details.

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing or wrong. In schemaPairs, fill both names or neither
400INVALID_DATA_APP_API_KEYYou used a service token
400WORKSPACE_ID_ERRORNo workspace has this name
400CLIENT_ID_ERRORclientId is empty
400INVALID_DASHBOARD_IDA dashboard in the workspace already has this dashboardId
400TEMPLATE_DASHBOARD_ERRORNo dashboard in the workspace has the templateDashboardId
400DASHBOARD_CREATE_ERRORThe dashboard or the import failed. Nothing was kept. hint says what to check
400INVALID_DATAMART or DATAMART_TABLE_NOT_FOUNDThe accessSettings.datamartName is wrong
400FILE_UPLOAD_ERRORThe file is not JSON
400IMPORT_DASHBOARD_DATA_FILE_ERRORThe file field is not named importDashboardDataFile
403entitlement_requiredYour plan does not include embedding
500INTERNAL_SERVER_ERRORThe request failed, for example the file is not valid JSON

For errors that every endpoint returns, see Authentication.

Example Request
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds' \  -H 'Content-Type: application/json' \  -d '{  "workspaceName": "Customer analytics",  "dashboardId": "acme-sales",  "clientId": "acme",  "name": "Acme sales",  "templateDashboardId": "sales-overview",  "isImportMetrics": true,  "accessSettings": {    "datamartName": "Sales",    "metricCreationMode": "DRAG_DROP",    "isAllowEmailReports": true,    "isAllowManageMetrics": true,    "isAllowCreateDashboardView": true,    "isAllowMetricCreation": true,    "isAllowMetricDeletion": true,    "isAllowMetricLayoutChange": true,    "isAllowMetricUpdate": true,    "isAllowUnderlyingData": true  }}'
Example Response
{  "id": "acme-sales",  "name": "Acme sales",  "importSummary": {    "imported": 8,    "skipped": 1,    "skippedMetrics": [      {        "metricId": "b3c4d5e6-f7a8-4b9c-8d0e-1f2a3b4c5d6e",        "name": "Churn",        "reason": "TARGET_TABLE_NOT_FOUND"      }    ]  }}