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,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: 'dash_12345',
    embedType: 'dashboard',
    workspaceName: 'analytics-workspace',
    name: 'Sales Dashboard Embed',
    accessSettings: {
      datamartName: 'sales-data',
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowCreateDashboardView: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Embed configuration ID:', data.id);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}
payload = {
    "dashboardId": "dash_12345",
    "embedType": "dashboard",
    "workspaceName": "analytics-workspace",
    "name": "Sales Dashboard Embed",
    "accessSettings": {
        "datamartName": "sales-data",
        "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowCreateDashboardView": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "joinModel": "multi",
        "metricCreationMode": "DRAG_DROP",
        "tableTenancySettings": [
            {
                "name": "sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Embed configuration ID: {data['id']}")

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

{
  "error": {
    "code": "INVALID_WORKSPACE_NAME",
    "message": "Invalid workspace name",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard not found",
    "status": 404
  }
}

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,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: 'dash_12345',
    embedType: 'dashboard',
    workspaceName: 'analytics-workspace',
    name: 'Sales Dashboard Embed',
    accessSettings: {
      datamartName: 'sales-data',
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowCreateDashboardView: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Embed configuration ID:', data.id);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}
payload = {
    "dashboardId": "dash_12345",
    "embedType": "dashboard",
    "workspaceName": "analytics-workspace",
    "name": "Sales Dashboard Embed",
    "accessSettings": {
        "datamartName": "sales-data",
        "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowCreateDashboardView": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "joinModel": "multi",
        "metricCreationMode": "DRAG_DROP",
        "tableTenancySettings": [
            {
                "name": "sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Embed configuration ID: {data['id']}")

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

{
  "error": {
    "code": "INVALID_WORKSPACE_NAME",
    "message": "Invalid workspace name",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard not found",
    "status": 404
  }
}

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,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: 'dash_12345',
    embedType: 'dashboard',
    workspaceName: 'analytics-workspace',
    name: 'Sales Dashboard Embed',
    accessSettings: {
      datamartName: 'sales-data',
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowCreateDashboardView: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Embed configuration ID:', data.id);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}
payload = {
    "dashboardId": "dash_12345",
    "embedType": "dashboard",
    "workspaceName": "analytics-workspace",
    "name": "Sales Dashboard Embed",
    "accessSettings": {
        "datamartName": "sales-data",
        "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowCreateDashboardView": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "joinModel": "multi",
        "metricCreationMode": "DRAG_DROP",
        "tableTenancySettings": [
            {
                "name": "sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Embed configuration ID: {data['id']}")

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

{
  "error": {
    "code": "INVALID_WORKSPACE_NAME",
    "message": "Invalid workspace name",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard not found",
    "status": 404
  }
}

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,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: 'dash_12345',
    embedType: 'dashboard',
    workspaceName: 'analytics-workspace',
    name: 'Sales Dashboard Embed',
    accessSettings: {
      datamartName: 'sales-data',
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowCreateDashboardView: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Embed configuration ID:', data.id);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}
payload = {
    "dashboardId": "dash_12345",
    "embedType": "dashboard",
    "workspaceName": "analytics-workspace",
    "name": "Sales Dashboard Embed",
    "accessSettings": {
        "datamartName": "sales-data",
        "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowCreateDashboardView": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "joinModel": "multi",
        "metricCreationMode": "DRAG_DROP",
        "tableTenancySettings": [
            {
                "name": "sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Embed configuration ID: {data['id']}")

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

{
  "error": {
    "code": "INVALID_WORKSPACE_NAME",
    "message": "Invalid workspace name",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard not found",
    "status": 404
  }
}

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

string

required

Bearer token for API authentication. Use your API key from the data app.

Authorization: Bearer dbn_live_abc123...

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

string

required

Existing dashboard ID to embed. This dashboard must already exist in your workspace.

'dashboard' | 'metric'

required

Type of embed configuration: dashboard or metric.

string

Metric ID to embed. Required if embedType is metric.

string

required

The name of the workspace where the embed configuration will be created.

string

Optional human-readable name for the embed configuration. If not provided, the embed ID will be used as the name.

object

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

string

required

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

boolean

Allow AI Pilot features (optional).

boolean

required

Allow sending email reports.

boolean

required

Allow managing metrics.

boolean

required

Allow creating dashboard views.

boolean

Optional. Enables end-user dashboard filter interactions in embedded mode.

array

Optional allowlist for dashboard filterable columns. Each item must include tableName and columns.

string

required

Fully qualified table name used in dashboard filters.

array[string]

required

Column names allowed for dashboard filter evaluation for the specified table.

boolean

required

Allow metric creation.

boolean

required

Allow metric deletion.

boolean

required

Allow metric layout changes.

boolean

required

Allow updating metrics.

boolean

required

Allow viewing underlying data.

'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)

boolean

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

'DRAG_DROP' | 'CHAT'

required

Mode of metric creation (drag and drop or chat).

array

Multi-tenant table access configuration (optional).

string

Table name for tenancy configuration. Required when tableTenancySettings is provided.

string

Column name for client-level filtering. Required when tableTenancySettings is provided.

Response

string

Unique identifier for the created embed configuration.

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

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Embed a Pre-built Dashboard/Metric

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

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