Create Embed Configuration

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",
    "accessSettings": {
      "datamartName": "sales-data",
      "isAllowAiPilot": true,
      "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
}

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",
    "accessSettings": {
      "datamartName": "sales-data",
      "isAllowAiPilot": true,
      "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
}

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",
    "accessSettings": {
      "datamartName": "sales-data",
      "isAllowAiPilot": true,
      "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

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",
    "metricId":"metric_123"   ///Required if embed type as metric
    "embedType": "dashboard"|"metric",
    "workspaceName": "analytics-workspace",
    "accessSettings": {
      "datamartName": "sales-data",
      "isAllowAiPilot": true,
      "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

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.

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.

accessSettings

object

required

Access control settings for the embedded view.

accessSettings.datamartName

string

required

The datamart name used in the embedded environment.

accessSettings.isAllowAiPilot

boolean

required

Allow AI pilot features.

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

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	Solution
`INVALID_WORKSPACE_NAME`	404	Workspace not found	Verify workspace exists and you have access
`INVALID_DATA_APP_API_KEY`	401	Invalid API key	Check your API key and permissions
`INVALID_DASHBOARD_ID`	404	Dashboard not found	Verify dashboard ID exists in workspace
`INVALID_METRIC_ID`	404	Metric not found	Verify metric ID exists (required for metric embeds)
`INTERNAL_SERVER_ERROR`	500	Server error	Contact support if error persists

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",
      "isAllowAiPilot": true,
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowCreateDashboardView": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "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 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

Embed Data App API (CRUD)

Create Dashboard Embed Configuration

⌘I

Authentication

Datamart APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

Create Embed Configuration

Endpoint Formats

Authentication

Headers

Request Body

Response

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Next Steps

Generate Guest Token

Create New Dashboard

Update Embed Config

How to Embed

Authentication

Datamart APIs

Embed Configuration

Embedding APIs (Legacy)

Data App APIs

​Endpoint Formats

​Authentication

​Headers

​Request Body

​Response

​HTTP Status Code Summary

​Possible Errors

​Quick Start Guide

​Next Steps

Generate Guest Token

Create New 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