Embeds
Embed a dashboard or metric
Add a workspace dashboard or metric to a data app, with what your customers can do in it.
curl --request POST https://api.usedatabrain.com/api/v2/data-app/embeds \ --header "Authorization: Bearer $DATABRAIN_API_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "workspaceName": "Customer analytics", "dashboardId": "sales-overview", "embedType": "dashboard", "name": "Sales overview", "accessSettings": { "datamartName": "Sales", "metricCreationMode": "DRAG_DROP", "isAllowEmailReports": true, "isAllowManageMetrics": false, "isAllowCreateDashboardView": true, "isAllowMetricCreation": false, "isAllowMetricDeletion": false, "isAllowMetricLayoutChange": true, "isAllowMetricUpdate": false, "isAllowUnderlyingData": true } }'Before you start
- You have a data app API token for the data app. A service token does not work here. See Authentication.
- Your plan includes embedding.
- You have the dashboard's
externalDashboardId. See Fetch dashboards by workspace.
DataAppApiTokenAuthorizationBearer <token>A data app API token. A service token is refused.
Body
Unknown fields are refused.
The workspace of the dashboard.
The dashboard's externalDashboardId
dashboard or metric
Required for metric. A metric on that dashboard.
Required for dashboard. What your customers can do. Metric embeds ignore it.
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 columnsDisplay name. Default: the embed id.
Description.
Response
{ "id": "sales-overview", "name": "Sales overview" }id is the embed id. Use it in the web component and in the other embed calls. If the data app already embeds this dashboard or metric, the new id gets a suffix, for example sales-overview__a1B2c3D4. Each call makes a new embed.
Errors
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | A field is missing, unknown or wrong |
| 400 | INVALID_DATA_APP_API_KEY | You used a service token, or the token has no data app |
| 400 | WORKSPACE_ID_ERROR | No workspace has this name |
| 400 | INVALID_DASHBOARD_ID | No dashboard in the workspace has this id |
| 400 | INVALID_METRIC_ID | The metric is not on that dashboard |
| 400 | INVALID_DATAMART | No datamart has this name, or its tenancy does not match the workspace |
| 400 | DATAMART_TABLE_NOT_FOUND | The datamart has table tenancy but no tables |
| 403 | entitlement_required | Your plan does not include embedding |
For errors that every endpoint returns, see Authentication.
Next, create a guest token to show the embed.
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/embeds' \ -H 'Content-Type: application/json' \ -d '{ "workspaceName": "Customer analytics", "dashboardId": "sales-overview", "embedType": "dashboard", "name": "Sales overview", "accessSettings": { "datamartName": "Sales", "metricCreationMode": "DRAG_DROP", "isAllowEmailReports": true, "isAllowManageMetrics": false, "isAllowCreateDashboardView": true, "isAllowMetricCreation": false, "isAllowMetricDeletion": false, "isAllowMetricLayoutChange": true, "isAllowMetricUpdate": false, "isAllowUnderlyingData": true }}'{ "id": "sales-overview", "name": "Sales overview"}