curl --request POST \
  --url https://api.usedatabrain.com/api/v2/dataApp/dashboardEmbed/create \
  --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,
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowAiPilot": true,
      "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
/
api
/
v2
/
dataApp
/
dashboardEmbed
/
create
curl --request POST \
  --url https://api.usedatabrain.com/api/v2/dataApp/dashboardEmbed/create \
  --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,
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowAiPilot": true,
      "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 blank dashboard in your data app. This endpoint is designed for multi-tenant scenarios where each client needs their own dashboard instance. Use templateDashboardId to clone filters and settings from an existing dashboard.
This endpoint creates a new dashboard. To embed an existing dashboard from your workspace, use the Create Embed Configuration endpoint instead.

​
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).
​
accessSettings
object
required
Access control settings for the dashboard.
​
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.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

​
id
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 CodeDescription
200OK - Dashboard created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
500Internal Server Error - Server error occurred

​
Possible Errors

CodeMessageHTTP Status
WORKSPACE_ID_ERRORInvalid workspace name400
INVALID_DATA_APP_API_KEYInvalid Data App API key401
CLIENT_ID_ERRORInvalid client id400
INVALID_DASHBOARD_IDDashboard already exists400
TEMPLATE_DASHBOARD_ERRORInvalid template dashboard id400
DASHBOARD_CREATE_ERRORFailed to create client dashboard500
INTERNAL_SERVER_ERRORInternal server error500

​
Quick Start Guide

1

Get your API token

For detailed instructions, see the API Token guide.
2

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/dataApp/dashboardEmbed/create \
  --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",
      "isAllowAiPilot": true,
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowCreateDashboardView": true,
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "metricCreationMode": "DRAG_DROP"
    }
  }'
3

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

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

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 Existing Dashboard

Learn how to embed existing dashboards instead

How to Embed

Integrate dashboards into your application

Multi-Tenant Access Control

Set up row-level security for your dashboards