Embed a Pre-built Dashboard/Metric

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",
    "embedType": "dashboard",
    "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,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "embed_abc123def456",
  "error": null
}

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",
    "embedType": "dashboard",
    "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,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "embed_abc123def456",
  "error": null
}

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",
    "embedType": "dashboard",
    "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,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "embed_abc123def456",
  "error": null
}

POST

api

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",
    "embedType": "dashboard",
    "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,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "embed_abc123def456",
  "error": null
}

Embed existing dashboards or metrics from your workspace. Use this endpoint when a dashboard has already been created in the DataBrain platform and you want to make it available for embedding in your application.

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 empty dashboard for multi-tenant scenarios, use the Create an Empty Dashboard Embed endpoint instead.

Endpoint Formats

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

POST https://api.usedatabrain.com/api/v2/data-app/embeds

Use this endpoint for all new integrations. This is the recommended endpoint format.

POST https://api.usedatabrain.com/api/v2/dataApp/embeds

This endpoint still works but will be deprecated. Please migrate to the new endpoint format.

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

Access control settings for the embedded view. Required when embedType is dashboard. Optional when embedType is metric.

accessSettings.datamartName

string

required

The datamart name used in the embedded environment. Required when embedType is dashboard.

accessSettings.isAllowAiPilot

boolean

Allow AI Pilot features (optional).

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.joinModel

'single' | 'multi'

Recommended join strategy for table relationships.

single: single worksheet mode (tables are pre-joined into one worksheet)
multi: multi-sheet mode (joins are resolved dynamically based on fields used in each chart)

accessSettings.isIncrementalJoin

boolean

Legacy join strategy flag. Prefer using accessSettings.joinModel instead.

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

string

Unique identifier for the created embed configuration.

error

null | object

Error object if the request failed, otherwise null.

HTTP Status Code Summary

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

Possible Errors

Error Code	HTTP Status	Description
`INVALID_WORKSPACE_NAME`	404	Workspace not found
`INVALID_DATA_APP_API_KEY`	401	Invalid API key
`INVALID_DASHBOARD_ID`	404	Dashboard not found
`INVALID_METRIC_ID`	404	Metric not found
`INTERNAL_SERVER_ERROR`	500	Server error

Quick Start Guide

Get your API token

For detailed instructions, see the API Token guide.

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.

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,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP"
    }
  }'

(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
}

Generate a guest token

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

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 an Empty Dashboard

Create new empty dashboards for multi-tenant scenarios

Update Embed Config

Modify existing embed configurations

How to Embed

Learn how to integrate embeds in your application

Embed Data App API (CRUD)

Create an Empty Dashboard Embed

​Endpoint Formats

​Authentication

​Headers

​Request Body

​Response

​HTTP Status Code Summary

​Possible Errors

​Quick Start Guide

​Next Steps

Generate Guest Token

Create an Empty Dashboard

Update Embed Config

How to Embed

Endpoint Formats

Authentication

Headers

Request Body

Response

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Next Steps