Skip to Content

Embeds

Embed a dashboard or metric

Add a workspace dashboard or metric to a data app, with what your customers can do in it.

POST
/api/v2/data-app/embeds
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.

Authorization

DataAppApiToken
headerAuthorizationBearer <token>

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

Body

Unknown fields are refused.

workspaceNamestringrequired

The workspace of the dashboard.

dashboardIdstringrequired

The dashboard's externalDashboardId

embedTypestringrequired

dashboard or metric

metricIdstring

Required for metric. A metric on that dashboard.

Required for dashboard. What your customers can do. Metric embeds ignore it.

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

Display 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

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing, unknown or wrong
400INVALID_DATA_APP_API_KEYYou used a service token, or the token has no data app
400WORKSPACE_ID_ERRORNo workspace has this name
400INVALID_DASHBOARD_IDNo dashboard in the workspace has this id
400INVALID_METRIC_IDThe metric is not on that dashboard
400INVALID_DATAMARTNo datamart has this name, or its tenancy does not match the workspace
400DATAMART_TABLE_NOT_FOUNDThe datamart has table tenancy but no tables
403entitlement_requiredYour plan does not include embedding

For errors that every endpoint returns, see Authentication.

Next, create a guest token to show the embed.

Example Request
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  }}'
Example Response
{  "id": "sales-overview",  "name": "Sales overview"}