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.
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.
DataAppApiTokenAuthorizationBearer <token>A data app API token. A service token is refused.
Body
Send JSON, or multipart/form-data to upload an export file.
The workspace for the new dashboard.
Id of the new dashboard, also the embed id. No dashboard in the workspace may have it.
The customer who owns the dashboard. Same value as the guest token's clientId
Same fields as Embed a dashboard or metric
19 fields in accessSettings
The datamart the embed queries. Its tenancy must match the workspace.
Create metrics with DRAG_DROP or CHAT
Schedule email reports.
Manage metrics.
Save dashboard views.
Create metrics.
Delete metrics.
Move and resize metrics.
Edit metrics.
See the underlying data.
Import a dashboard that uses another tenant's metrics, rebound to their own tenant.
falsemulti lets metrics join tables. single does not.
The tenant column per table: { "name": "orders", "clientColumn": "customer_id" }. name has no schema.
From the datamart2 fields in tableTenancySettings
Columns they can filter dashboards on: { "tableName": "public.orders", "columns": ["region"] }
All columnsEmbed name. Default: dashboardId
Embed description.
Give the dashboard the name too. Otherwise it is named <dashboardId>_<clientId>
falseA 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
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.
Schema names to swap in imported SQL: { "replaceSchema": "staging", "targetSchema": "public" }
2 fields in schemaPairs
Multipart only: the export as a .json file. Overrides importDashboardData
binaryWith 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.
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | A field is missing or wrong. In schemaPairs, fill both names or neither |
| 400 | INVALID_DATA_APP_API_KEY | You used a service token |
| 400 | WORKSPACE_ID_ERROR | No workspace has this name |
| 400 | CLIENT_ID_ERROR | clientId is empty |
| 400 | INVALID_DASHBOARD_ID | A dashboard in the workspace already has this dashboardId |
| 400 | TEMPLATE_DASHBOARD_ERROR | No dashboard in the workspace has the templateDashboardId |
| 400 | DASHBOARD_CREATE_ERROR | The dashboard or the import failed. Nothing was kept. hint says what to check |
| 400 | INVALID_DATAMART or DATAMART_TABLE_NOT_FOUND | The accessSettings.datamartName is wrong |
| 400 | FILE_UPLOAD_ERROR | The file is not JSON |
| 400 | IMPORT_DASHBOARD_DATA_FILE_ERROR | The file field is not named importDashboardDataFile |
| 403 | entitlement_required | Your plan does not include embedding |
| 500 | INTERNAL_SERVER_ERROR | The request failed, for example the file is not valid JSON |
For errors that every endpoint returns, see Authentication.
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 }}'{ "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" } ] }}