Skip to main content
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "dash_12345",
    "metricId":"metric_123"   ///Required if embed type as metric
    "embedType": "dashboard"|"metric",
    "workspaceName": "analytics-workspace",
    "name": "Sales Dashboard Embed",
    "accessSettings": {
      "datamartName": "sales-data",
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowCreateDashboardView": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "metricCreationMode": "DRAG_DROP"|"CHAT",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "embed_abc123def456",
  "error": null
}
POST
https://api.usedatabrain.com
/
api
/
v2
/
data-app
/
embeds
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "dash_12345",
    "metricId":"metric_123"   ///Required if embed type as metric
    "embedType": "dashboard"|"metric",
    "workspaceName": "analytics-workspace",
    "name": "Sales Dashboard Embed",
    "accessSettings": {
      "datamartName": "sales-data",
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowCreateDashboardView": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "metricCreationMode": "DRAG_DROP"|"CHAT",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "embed_abc123def456",
  "error": null
}
Create secure embed configurations for existing dashboards or metrics from your workspace. This endpoint allows you to share pre-built dashboards and metrics with external users by making them embeddable in your data app.
Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/embeds. The old endpoint /api/v2/dataApp/embeds will be deprecated soon. Please update your integrations to use the new endpoint format.
This endpoint embeds existing dashboards/metrics from your workspace. To create a new blank dashboard for multi-tenant scenarios, use the Create Dashboard Embed endpoint instead.

​
Endpoint Formats

​
Authentication

All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our data app creation guide for details. Finding your API token: For detailed instructions, see the API Token guide.

​
Headers

​
Authorization
string
required
Bearer token for API authentication. Use your API key from the data app.
Authorization: Bearer dbn_live_abc123...
​
Content-Type
string
required
Must be set to application/json for all requests.
Content-Type: application/json

​
Request Body

​
dashboardId
string
required
Existing dashboard ID to embed. This dashboard must already exist in your workspace.
​
embedType
'dashboard' | 'metric'
required
Type of embed configuration: dashboard or metric.
​
metricId
string
Metric ID to embed. Required if embedType is metric.
​
workspaceName
string
required
The name of the workspace where the embed configuration will be created.
​
name
string
Optional human-readable name for the embed configuration. If not provided, the embed ID will be used as the name.
​
accessSettings
object
required
Access control settings for the embedded view.
​
accessSettings.datamartName
string
required
The datamart name used in the embedded environment.
​
accessSettings.isAllowEmailReports
boolean
required
Allow sending email reports.
​
accessSettings.isAllowManageMetrics
boolean
required
Allow managing metrics.
​
accessSettings.isAllowCreateDashboardView
boolean
required
Allow creating dashboard views.
​
accessSettings.isAllowMetricCreation
boolean
required
Allow metric creation.
​
accessSettings.isAllowMetricDeletion
boolean
required
Allow metric deletion.
​
accessSettings.isAllowMetricLayoutChange
boolean
required
Allow metric layout changes.
​
accessSettings.isAllowMetricUpdate
boolean
required
Allow updating metrics.
​
accessSettings.isAllowUnderlyingData
boolean
required
Allow viewing underlying data.
​
accessSettings.metricCreationMode
'DRAG_DROP' | 'CHAT'
required
Mode of metric creation (drag and drop or chat).
​
accessSettings.tableTenancySettings
array
Multi-tenant table access configuration (optional).
​
accessSettings.tableTenancySettings[].name
string
Table name for tenancy configuration.
​
accessSettings.tableTenancySettings[].clientColumn
string
Column name for client-level filtering.

​
Response

​
id
string
Unique identifier for the created embed configuration.
​
error
null | object
Error object if the request failed, otherwise null.

​
HTTP Status Code Summary

Status CodeDescription
200OK - Embed configuration created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
404Not Found - Dashboard or metric not found
500Internal Server Error - Server error occurred

​
Possible Errors

Error CodeHTTP StatusDescription
INVALID_WORKSPACE_NAME404Workspace not found
INVALID_DATA_APP_API_KEY401Invalid API key
INVALID_DASHBOARD_ID404Dashboard not found
INVALID_METRIC_ID404Metric not found
INTERNAL_SERVER_ERROR500Server error

​
Quick Start Guide

1

Get your API token

For detailed instructions, see the API Token guide.
2

Create a dashboard in your workspace

First, create and configure your dashboard in the DataBrain workspace with all the metrics and visualizations you want to embed.
3

Create embed configuration for dashboard

Make a POST request to embed your existing dashboard:
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "existing-dashboard-id",
    "embedType": "dashboard",
    "workspaceName": "my-workspace",
    "accessSettings": {
      "datamartName": "my-datamart",
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowCreateDashboardView": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "metricCreationMode": "DRAG_DROP"
    }
  }'
4

(Optional) Embed a single metric

To embed just one metric instead of the entire dashboard, use embedType: "metric":
{
  "dashboardId": "existing-dashboard-id",
  "embedType": "metric",
  "metricId": "metric-123",
  "workspaceName": "my-workspace",
  // ... accessSettings
}
5

Generate a guest token

Use the embed ID to generate a guest token for your end users. See the Guest Token API for details.
6

Embed in your application

Use the embed ID and guest token in your web component:
<dbn-dashboard 
  token="guest-token-here" 
  dashboard-id="existing-dashboard-id" 
/>

​
Next Steps

Generate Guest Token

Create secure tokens for your embed configurations

Create New Dashboard

Create new blank dashboards for multi-tenant scenarios

Update Embed Config

Modify existing embed configurations

How to Embed

Learn how to integrate embeds in your application