Create an Empty Dashboard Embed

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "client-acme-dashboard",
    "clientId": "acme-corp-123",
    "workspaceName": "analytics-workspace",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "client-acme-dashboard",
  "error": null
}

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "client-acme-dashboard",
    "clientId": "acme-corp-123",
    "workspaceName": "analytics-workspace",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "client-acme-dashboard",
  "error": null
}

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "client-acme-dashboard",
    "clientId": "acme-corp-123",
    "workspaceName": "analytics-workspace",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "client-acme-dashboard",
  "error": null
}

POST

https://api.usedatabrain.com

api

data-app

dashboard-embeds

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "client-acme-dashboard",
    "clientId": "acme-corp-123",
    "workspaceName": "analytics-workspace",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

{
  "id": "client-acme-dashboard",
  "error": null
}

Create a new empty dashboard in your data app. This endpoint is designed for multi-tenant scenarios where each client needs their own dashboard instance to build upon. Use templateDashboardId to clone filters and settings from an existing dashboard.

Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/dashboard-embeds. The old endpoint /api/v2/dataApp/dashboard-embeds will be deprecated soon. Please update your integrations to use the new endpoint format.

This endpoint creates a new empty dashboard. To embed an existing pre-built dashboard from your workspace, use the Embed a Pre-built Dashboard/Metric endpoint instead.

Endpoint Formats

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

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

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

POST https://api.usedatabrain.com/api/v2/dataApp/dashboard-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

Unique identifier for the new dashboard. Must be unique within the data app.

clientId

string

required

Client ID for the dashboard owner. Used for multi-tenant isolation and row-level security.

workspaceName

string

required

The name of the workspace where the dashboard will be created.

templateDashboardId

string

Dashboard ID to clone filters, grid margins, and layout settings from (optional).

metadata

object

Custom metadata for the dashboard (optional).

isAllowPrivateMetricsByDefault

boolean

Allow users to create private metrics visible only to them (optional).

name

string

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

accessSettings

object

required

Access control settings for the dashboard.

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

boolean

required

Allow metric creation.

accessSettings.isAllowMetricDeletion

boolean

required

Allow metric deletion.

accessSettings.isAllowMetricLayoutChange

boolean

required

Allow layout changes to metrics.

accessSettings.isAllowMetricUpdate

boolean

required

Allow updating metrics.

accessSettings.isAllowUnderlyingData

boolean

required

Allow viewing of underlying data.

accessSettings.isAllowCreateDashboardView

boolean

required

Allow creating dashboard views.

accessSettings.metricCreationMode

'DRAG_DROP' | 'CHAT'

required

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

accessSettings.tableTenancySettings

array

List of allowed tables in embed (optional).

accessSettings.tableTenancySettings[].clientColumn

string

Client-level column for table tenancy.

accessSettings.tableTenancySettings[].name

string

Table name.

Response

string

The ID of the created dashboard embed configuration.

error

null | object

Error object if the request failed, otherwise null.

HTTP Status Code Summary

Status Code	Description
`200`	OK - Dashboard created successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`500`	Internal Server Error - Server error occurred

Possible Errors

Code	Message	HTTP Status
`WORKSPACE_ID_ERROR`	Invalid workspace name	400
`INVALID_DATA_APP_API_KEY`	Invalid Data App API key	401
`CLIENT_ID_ERROR`	Invalid client id	400
`INVALID_DASHBOARD_ID`	Dashboard already exists	400
`TEMPLATE_DASHBOARD_ERROR`	Invalid template dashboard id	400
`DASHBOARD_CREATE_ERROR`	Failed to create client dashboard	500
`INTERNAL_SERVER_ERROR`	Internal server error	500

Quick Start Guide

Get your API token

For detailed instructions, see the API Token guide.

Create a new dashboard for your client

Make a POST request with the required parameters:

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "dashboardId": "client-acme-analytics",
    "clientId": "acme-corp-123",
    "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"
    }
  }'

(Optional) Use a template

To clone settings from an existing dashboard, add templateDashboardId:

{
  "dashboardId": "client-acme-analytics",
  "clientId": "acme-corp-123",
  "templateDashboardId": "template-dashboard-001",
  // ... rest of the configuration
}

Generate a guest token

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

Embed in your application

Use the dashboard ID and guest token in your web component:

<dbn-dashboard 
  token="guest-token-here" 
  dashboard-id="client-acme-analytics" 
/>

Use Cases

Multi-Tenant SaaS

Create isolated dashboards for each customer in your SaaS application.

Template-Based Creation

Use templateDashboardId to clone filters and settings from a master template.

Dynamic Provisioning

Automatically create dashboards during customer onboarding or upgrades.

Client Isolation

Ensure data isolation with clientId and row-level security settings.

Next Steps

Generate Guest Token

Create secure tokens to access your new dashboard

Embed a Pre-built Dashboard/Metric

Embed existing dashboards that were built in the databrain platform

How to Embed

Integrate dashboards into your application

Multi-Tenant Access Control

Set up row-level security for your dashboards

Embed a Pre-built Dashboard/Metric

List All Embeds

⌘I

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Embedding APIs (Legacy)

Data App APIs

Metric APIs

Create an Empty Dashboard Embed

Endpoint Formats

Authentication

Headers

Request Body

Response

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Use Cases

Multi-Tenant SaaS

Template-Based Creation

Dynamic Provisioning

Client Isolation

Next Steps

Generate Guest Token

Embed a Pre-built Dashboard/Metric

How to Embed

Multi-Tenant Access Control

Authentication

Datasource APIs

Datamart APIs

Workspace APIs

Embeds

Embedding APIs (Legacy)

Data App APIs

Metric APIs

​Endpoint Formats

​Authentication

​Headers

​Request Body

​Response

​HTTP Status Code Summary

​Possible Errors

​Quick Start Guide

​Use Cases

Multi-Tenant SaaS

Template-Based Creation

Dynamic Provisioning

Client Isolation

​Next Steps

Generate Guest Token

Embed a Pre-built Dashboard/Metric

How to Embed

Multi-Tenant Access Control

Endpoint Formats

Authentication

Headers

Request Body

Response

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Use Cases

Next Steps