Create a 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",
    "workspaceName": "analytics-workspace",
    "clientId": "acme-corp-123",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": true,
    "isRenameDashboard": true,
    "metricImportMode": "GALLERY",
    "importDashboardData": {
      "...": "dashboard configuration exported from the Export Dashboard or Export Embed Dashboard API"
    },
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": true,
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowEndUserMetricFilter": true,
      "metricFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --form 'dashboardId=client-acme-dashboard' \
  --form 'workspaceName=analytics-workspace' \
  --form 'clientId=acme-corp-123' \
  --form 'name=ACME Analytics Dashboard' \
  --form 'isRenameDashboard=true' \
  --form 'accessSettings={"datamartName":"customer-analytics","isAllowEmailReports":false,"isAllowManageMetrics":true,"isAllowEndUserMetricFilter":true,"metricFilterColumns":[{"tableName":"public.sales_data","columns":["region","order_date"]}],"isAllowMetricCreation":true,"isAllowMetricDeletion":false,"isAllowMetricLayoutChange":true,"isAllowMetricUpdate":true,"isAllowUnderlyingData":false,"isAllowCreateDashboardView":true,"joinModel":"multi","metricCreationMode":"DRAG_DROP"}' \
  --form 'importDashboardDataFile=@./dashboard-export.json;type=application/json'

{
  "dashboardId": "imported-dashboard-103",
  "workspaceName": "AA",
  "clientId": "103",
  "name": "Imported dashboard 103",
  "metricImportMode": "METRIC",
  "importDashboardData": {},
  "accessSettings": {
    "datamartName": "aa-import-datamart",
    "isAllowCrossTenantDashboardImport": true,
    "isAllowEmailReports": false,
    "isAllowManageMetrics": true,
    "isAllowCreateDashboardView": false,
    "isAllowMetricCreation": true,
    "isAllowMetricDeletion": true,
    "isAllowMetricLayoutChange": true,
    "isAllowMetricUpdate": true,
    "isAllowUnderlyingData": true,
    "metricCreationMode": "DRAG_DROP"
  }
}

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: `client-${clientId}-dashboard`,
    workspaceName: 'analytics-workspace',
    clientId: clientId,
    templateDashboardId: 'template-dashboard-001',
    metadata: {
      clientName: 'Acme Corporation',
      createdAt: new Date().toISOString()
    },
    isAllowPrivateMetricsByDefault: false,
    name: 'ACME Analytics Dashboard',
    embedDescription: 'Analytics dashboard for ACME Corp',
    isImportMetrics: true,
    isRenameDashboard: true,
    metricImportMode: 'GALLERY',
    importDashboardData: exportedDashboard.data, // from Export Dashboard or Export Embed Dashboard API
    accessSettings: {
      datamartName: 'customer-analytics',
      isAllowAiPilot: true,
      isAllowCrossTenantDashboardImport: true,
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowEndUserMetricFilter: true,
      metricFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      isAllowCreateDashboardView: true,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('New dashboard ID:', data.id, 'Name:', data.name);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}

payload = {
    "dashboardId": f"client-{client_id}-dashboard",
    "workspaceName": "analytics-workspace",
    "clientId": client_id,
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
        "clientName": "Acme Corporation",
        "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": False,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": True,
    "isRenameDashboard": True,
    "metricImportMode": "GALLERY",
    "importDashboardData": exported_dashboard["data"],  # from Export Dashboard or Export Embed Dashboard API
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": True,
      "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowEndUserMetricFilter": True,
        "metricFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "isAllowCreateDashboardView": True,
        "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"New dashboard ID: {data['id']}, Name: {data.get('name')}")

{
  "id": "client-acme-dashboard",
  "error": null,
  "name": "ACME Analytics Dashboard"
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"accessSettings\" is required",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard already exists",
    "status": 400
  }
}

{
  "error": {
    "code": "DASHBOARD_CREATE_ERROR",
    "message": "Source dashboard is outside the authorized scope"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Invalid Data App API key",
    "status": 401
  }
}

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",
    "workspaceName": "analytics-workspace",
    "clientId": "acme-corp-123",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": true,
    "isRenameDashboard": true,
    "metricImportMode": "GALLERY",
    "importDashboardData": {
      "...": "dashboard configuration exported from the Export Dashboard or Export Embed Dashboard API"
    },
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": true,
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowEndUserMetricFilter": true,
      "metricFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --form 'dashboardId=client-acme-dashboard' \
  --form 'workspaceName=analytics-workspace' \
  --form 'clientId=acme-corp-123' \
  --form 'name=ACME Analytics Dashboard' \
  --form 'isRenameDashboard=true' \
  --form 'accessSettings={"datamartName":"customer-analytics","isAllowEmailReports":false,"isAllowManageMetrics":true,"isAllowEndUserMetricFilter":true,"metricFilterColumns":[{"tableName":"public.sales_data","columns":["region","order_date"]}],"isAllowMetricCreation":true,"isAllowMetricDeletion":false,"isAllowMetricLayoutChange":true,"isAllowMetricUpdate":true,"isAllowUnderlyingData":false,"isAllowCreateDashboardView":true,"joinModel":"multi","metricCreationMode":"DRAG_DROP"}' \
  --form 'importDashboardDataFile=@./dashboard-export.json;type=application/json'

{
  "dashboardId": "imported-dashboard-103",
  "workspaceName": "AA",
  "clientId": "103",
  "name": "Imported dashboard 103",
  "metricImportMode": "METRIC",
  "importDashboardData": {},
  "accessSettings": {
    "datamartName": "aa-import-datamart",
    "isAllowCrossTenantDashboardImport": true,
    "isAllowEmailReports": false,
    "isAllowManageMetrics": true,
    "isAllowCreateDashboardView": false,
    "isAllowMetricCreation": true,
    "isAllowMetricDeletion": true,
    "isAllowMetricLayoutChange": true,
    "isAllowMetricUpdate": true,
    "isAllowUnderlyingData": true,
    "metricCreationMode": "DRAG_DROP"
  }
}

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: `client-${clientId}-dashboard`,
    workspaceName: 'analytics-workspace',
    clientId: clientId,
    templateDashboardId: 'template-dashboard-001',
    metadata: {
      clientName: 'Acme Corporation',
      createdAt: new Date().toISOString()
    },
    isAllowPrivateMetricsByDefault: false,
    name: 'ACME Analytics Dashboard',
    embedDescription: 'Analytics dashboard for ACME Corp',
    isImportMetrics: true,
    isRenameDashboard: true,
    metricImportMode: 'GALLERY',
    importDashboardData: exportedDashboard.data, // from Export Dashboard or Export Embed Dashboard API
    accessSettings: {
      datamartName: 'customer-analytics',
      isAllowAiPilot: true,
      isAllowCrossTenantDashboardImport: true,
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowEndUserMetricFilter: true,
      metricFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      isAllowCreateDashboardView: true,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('New dashboard ID:', data.id, 'Name:', data.name);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}

payload = {
    "dashboardId": f"client-{client_id}-dashboard",
    "workspaceName": "analytics-workspace",
    "clientId": client_id,
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
        "clientName": "Acme Corporation",
        "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": False,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": True,
    "isRenameDashboard": True,
    "metricImportMode": "GALLERY",
    "importDashboardData": exported_dashboard["data"],  # from Export Dashboard or Export Embed Dashboard API
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": True,
      "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowEndUserMetricFilter": True,
        "metricFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "isAllowCreateDashboardView": True,
        "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"New dashboard ID: {data['id']}, Name: {data.get('name')}")

{
  "id": "client-acme-dashboard",
  "error": null,
  "name": "ACME Analytics Dashboard"
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"accessSettings\" is required",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard already exists",
    "status": 400
  }
}

{
  "error": {
    "code": "DASHBOARD_CREATE_ERROR",
    "message": "Source dashboard is outside the authorized scope"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Invalid Data App API key",
    "status": 401
  }
}

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",
    "workspaceName": "analytics-workspace",
    "clientId": "acme-corp-123",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": true,
    "isRenameDashboard": true,
    "metricImportMode": "GALLERY",
    "importDashboardData": {
      "...": "dashboard configuration exported from the Export Dashboard or Export Embed Dashboard API"
    },
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": true,
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowEndUserMetricFilter": true,
      "metricFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --form 'dashboardId=client-acme-dashboard' \
  --form 'workspaceName=analytics-workspace' \
  --form 'clientId=acme-corp-123' \
  --form 'name=ACME Analytics Dashboard' \
  --form 'isRenameDashboard=true' \
  --form 'accessSettings={"datamartName":"customer-analytics","isAllowEmailReports":false,"isAllowManageMetrics":true,"isAllowEndUserMetricFilter":true,"metricFilterColumns":[{"tableName":"public.sales_data","columns":["region","order_date"]}],"isAllowMetricCreation":true,"isAllowMetricDeletion":false,"isAllowMetricLayoutChange":true,"isAllowMetricUpdate":true,"isAllowUnderlyingData":false,"isAllowCreateDashboardView":true,"joinModel":"multi","metricCreationMode":"DRAG_DROP"}' \
  --form 'importDashboardDataFile=@./dashboard-export.json;type=application/json'

{
  "dashboardId": "imported-dashboard-103",
  "workspaceName": "AA",
  "clientId": "103",
  "name": "Imported dashboard 103",
  "metricImportMode": "METRIC",
  "importDashboardData": {},
  "accessSettings": {
    "datamartName": "aa-import-datamart",
    "isAllowCrossTenantDashboardImport": true,
    "isAllowEmailReports": false,
    "isAllowManageMetrics": true,
    "isAllowCreateDashboardView": false,
    "isAllowMetricCreation": true,
    "isAllowMetricDeletion": true,
    "isAllowMetricLayoutChange": true,
    "isAllowMetricUpdate": true,
    "isAllowUnderlyingData": true,
    "metricCreationMode": "DRAG_DROP"
  }
}

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: `client-${clientId}-dashboard`,
    workspaceName: 'analytics-workspace',
    clientId: clientId,
    templateDashboardId: 'template-dashboard-001',
    metadata: {
      clientName: 'Acme Corporation',
      createdAt: new Date().toISOString()
    },
    isAllowPrivateMetricsByDefault: false,
    name: 'ACME Analytics Dashboard',
    embedDescription: 'Analytics dashboard for ACME Corp',
    isImportMetrics: true,
    isRenameDashboard: true,
    metricImportMode: 'GALLERY',
    importDashboardData: exportedDashboard.data, // from Export Dashboard or Export Embed Dashboard API
    accessSettings: {
      datamartName: 'customer-analytics',
      isAllowAiPilot: true,
      isAllowCrossTenantDashboardImport: true,
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowEndUserMetricFilter: true,
      metricFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      isAllowCreateDashboardView: true,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('New dashboard ID:', data.id, 'Name:', data.name);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}

payload = {
    "dashboardId": f"client-{client_id}-dashboard",
    "workspaceName": "analytics-workspace",
    "clientId": client_id,
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
        "clientName": "Acme Corporation",
        "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": False,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": True,
    "isRenameDashboard": True,
    "metricImportMode": "GALLERY",
    "importDashboardData": exported_dashboard["data"],  # from Export Dashboard or Export Embed Dashboard API
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": True,
      "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowEndUserMetricFilter": True,
        "metricFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "isAllowCreateDashboardView": True,
        "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"New dashboard ID: {data['id']}, Name: {data.get('name')}")

{
  "id": "client-acme-dashboard",
  "error": null,
  "name": "ACME Analytics Dashboard"
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"accessSettings\" is required",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard already exists",
    "status": 400
  }
}

{
  "error": {
    "code": "DASHBOARD_CREATE_ERROR",
    "message": "Source dashboard is outside the authorized scope"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Invalid Data App API key",
    "status": 401
  }
}

POST

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",
    "workspaceName": "analytics-workspace",
    "clientId": "acme-corp-123",
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
      "clientName": "Acme Corporation",
      "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": false,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": true,
    "isRenameDashboard": true,
    "metricImportMode": "GALLERY",
    "importDashboardData": {
      "...": "dashboard configuration exported from the Export Dashboard or Export Embed Dashboard API"
    },
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": true,
      "isAllowEmailReports": false,
      "isAllowManageMetrics": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "isAllowEndUserMetricFilter": true,
      "metricFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["region", "order_date"]
        }
      ],
      "isAllowMetricCreation": true,
      "isAllowMetricDeletion": false,
      "isAllowMetricLayoutChange": true,
      "isAllowMetricUpdate": true,
      "isAllowUnderlyingData": false,
      "isAllowCreateDashboardView": true,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP",
      "tableTenancySettings": [
        {
          "name": "sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

curl --request POST \
  --url https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --form 'dashboardId=client-acme-dashboard' \
  --form 'workspaceName=analytics-workspace' \
  --form 'clientId=acme-corp-123' \
  --form 'name=ACME Analytics Dashboard' \
  --form 'isRenameDashboard=true' \
  --form 'accessSettings={"datamartName":"customer-analytics","isAllowEmailReports":false,"isAllowManageMetrics":true,"isAllowEndUserMetricFilter":true,"metricFilterColumns":[{"tableName":"public.sales_data","columns":["region","order_date"]}],"isAllowMetricCreation":true,"isAllowMetricDeletion":false,"isAllowMetricLayoutChange":true,"isAllowMetricUpdate":true,"isAllowUnderlyingData":false,"isAllowCreateDashboardView":true,"joinModel":"multi","metricCreationMode":"DRAG_DROP"}' \
  --form 'importDashboardDataFile=@./dashboard-export.json;type=application/json'

{
  "dashboardId": "imported-dashboard-103",
  "workspaceName": "AA",
  "clientId": "103",
  "name": "Imported dashboard 103",
  "metricImportMode": "METRIC",
  "importDashboardData": {},
  "accessSettings": {
    "datamartName": "aa-import-datamart",
    "isAllowCrossTenantDashboardImport": true,
    "isAllowEmailReports": false,
    "isAllowManageMetrics": true,
    "isAllowCreateDashboardView": false,
    "isAllowMetricCreation": true,
    "isAllowMetricDeletion": true,
    "isAllowMetricLayoutChange": true,
    "isAllowMetricUpdate": true,
    "isAllowUnderlyingData": true,
    "metricCreationMode": "DRAG_DROP"
  }
}

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dashboardId: `client-${clientId}-dashboard`,
    workspaceName: 'analytics-workspace',
    clientId: clientId,
    templateDashboardId: 'template-dashboard-001',
    metadata: {
      clientName: 'Acme Corporation',
      createdAt: new Date().toISOString()
    },
    isAllowPrivateMetricsByDefault: false,
    name: 'ACME Analytics Dashboard',
    embedDescription: 'Analytics dashboard for ACME Corp',
    isImportMetrics: true,
    isRenameDashboard: true,
    metricImportMode: 'GALLERY',
    importDashboardData: exportedDashboard.data, // from Export Dashboard or Export Embed Dashboard API
    accessSettings: {
      datamartName: 'customer-analytics',
      isAllowAiPilot: true,
      isAllowCrossTenantDashboardImport: true,
      isAllowEmailReports: false,
      isAllowManageMetrics: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      isAllowEndUserMetricFilter: true,
      metricFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['region', 'order_date']
        }
      ],
      isAllowMetricCreation: true,
      isAllowMetricDeletion: false,
      isAllowMetricLayoutChange: true,
      isAllowMetricUpdate: true,
      isAllowUnderlyingData: false,
      isAllowCreateDashboardView: true,
      joinModel: 'multi',
      metricCreationMode: 'DRAG_DROP',
      tableTenancySettings: [
        {
          name: 'sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('New dashboard ID:', data.id, 'Name:', data.name);

import requests
import json

url = "https://api.usedatabrain.com/api/v2/data-app/dashboard-embeds"
headers = {
    "Authorization": "Bearer dbn_live_abc123...",
    "Content-Type": "application/json"
}

payload = {
    "dashboardId": f"client-{client_id}-dashboard",
    "workspaceName": "analytics-workspace",
    "clientId": client_id,
    "templateDashboardId": "template-dashboard-001",
    "metadata": {
        "clientName": "Acme Corporation",
        "region": "North America"
    },
    "isAllowPrivateMetricsByDefault": False,
    "name": "ACME Analytics Dashboard",
    "embedDescription": "Analytics dashboard for ACME Corp",
    "isImportMetrics": True,
    "isRenameDashboard": True,
    "metricImportMode": "GALLERY",
    "importDashboardData": exported_dashboard["data"],  # from Export Dashboard or Export Embed Dashboard API
    "accessSettings": {
      "datamartName": "customer-analytics",
      "isAllowCrossTenantDashboardImport": True,
      "isAllowEmailReports": False,
        "isAllowManageMetrics": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "isAllowEndUserMetricFilter": True,
        "metricFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["region", "order_date"]
            }
        ],
        "isAllowMetricCreation": True,
        "isAllowMetricDeletion": False,
        "isAllowMetricLayoutChange": True,
        "isAllowMetricUpdate": True,
        "isAllowUnderlyingData": False,
        "isAllowCreateDashboardView": True,
        "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"New dashboard ID: {data['id']}, Name: {data.get('name')}")

{
  "id": "client-acme-dashboard",
  "error": null,
  "name": "ACME Analytics Dashboard"
}

{
  "error": {
    "code": "INVALID_REQUEST_BODY",
    "message": "\"accessSettings\" is required",
    "status": 400
  }
}

{
  "error": {
    "code": "INVALID_DASHBOARD_ID",
    "message": "Dashboard already exists",
    "status": 400
  }
}

{
  "error": {
    "code": "DASHBOARD_CREATE_ERROR",
    "message": "Source dashboard is outside the authorized scope"
  }
}

{
  "error": {
    "code": "INVALID_DATA_APP_API_KEY",
    "message": "Invalid Data App API key",
    "status": 401
  }
}

Create a new client dashboard in your data app. Each client gets their own dashboard instance. Start with an empty dashboard, use templateDashboardId to clone filters and settings, or provide dashboard export data to import its content.

Supplying templateDashboardId, importDashboardData, or importDashboardDataFile still creates a client end-user dashboard. To import a dashboard into your own workspace instead, use the Import Dashboard API with a service token.

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

string

required

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

Authorization: Bearer dbn_live_abc123...

string

required

Supported values:

application/json for pure JSON payloads
multipart/form-data when uploading a dashboard export JSON file via importDashboardDataFile

Content-Type: application/json

When using multipart/form-data, object/boolean/array fields (for example accessSettings, metadata, importDashboardData, isImportMetrics, isRenameDashboard, schemaPairs) can be sent as JSON strings. Databrain parses these before validation.

importDashboardDataFile is a multipart file field (not a JSON body field). The uploaded file must be sent with MIME type application/json and contain a top-level data object.

Request Body

string

required

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

string

required

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

string

required

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

string

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

object

Custom metadata for the dashboard (optional).

boolean

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

string

Human-readable name for the embed configuration (optional). If not provided, the dashboard ID is used as the name. When isRenameDashboard is true, this value is also used as the underlying dashboard’s display name.

string

Description for the embed configuration (optional).

boolean

When true and templateDashboardId is provided, metrics from the template dashboard are imported into the new dashboard (optional).

object

Full dashboard configuration to import into the newly created client dashboard (optional). This should be the data object from a dashboard export payload (for example, from the Export Dashboard API or the Export Embed Dashboard API). When importDashboardData is provided, Databrain skips templateDashboardId-based metric import and directly hydrates the new dashboard from this configuration.

file (.json)

Optional JSON file upload alternative to importDashboardData. Upload a dashboard export JSON file (the payload that contains a top-level data object). When provided, Databrain reads data from the file and uses it as importDashboardData.If both importDashboardData and importDashboardDataFile are provided, importDashboardDataFile takes precedence.

boolean

When true and name is provided, the created dashboard’s display name is set to name. When false or omitted, the dashboard name is set to {dashboardId}_{clientId} (optional). Defaults to false if omitted.

'GALLERY' | 'METRIC'

When isImportMetrics is true and templateDashboardId is provided, controls how metrics are imported: GALLERY or METRIC (optional).

array

Optional. Same shape as Import Dashboard schemaPairs: an array of objects; each object requires replaceSchema (string) and targetSchema (string). Use this when imported SQL references a schema name that should map to the target datamart schema.Typically used with importDashboardData or importDashboardDataFile. With multipart/form-data, send schemaPairs as a JSON-encoded string (see note above); the server parses it before Joi validation.

object

required

Access control settings for the dashboard.

string

required

The datamart name used in the embedded environment.

boolean

Allow AI Pilot features (optional).

boolean

required

Allow sending email reports.

boolean

required

Allow managing metrics.

boolean

Controls whether client-created metrics owned by a different client can be imported into this client dashboard (optional).

true: imports eligible metrics from another client and rebinds them to the destination clientId.
false or omitted : skips metrics owned by another client. Admin-created metrics and metrics already owned by the destination client remain eligible.

boolean

required

Allow metric creation.

boolean

required

Allow metric deletion.

boolean

required

Allow layout changes to metrics.

boolean

required

Allow end users to update supported metrics. This does not allow them to edit Custom SQL metrics.

boolean

required

Allow viewing of underlying data.

boolean

required

Allow creating dashboard views.

boolean

Optional. Enables end-user dashboard filter interactions in embedded mode. It does not allow end users to submit dashboard filter definitions containing Custom SQL.

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

Optional. Enables end-user metric filter interactions in embedded mode. It does not allow end users to submit metric filter definitions containing Custom SQL.

array

Optional allowlist for columns that end users can use in metric filters. Each item must include tableName and columns.

string

required

Fully qualified table name used in metric filters.

array[string]

required

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

'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

List of allowed tables and client columns for table tenancy (optional). When provided, each item must include name and clientColumn.

string

Table name. Required when the parent tableTenancySettings array is provided.

string

Client-level column for table tenancy. Required when the parent tableTenancySettings array is provided.

Dashboard import formats

This endpoint supports two import formats:

Format	Field	Content type
JSON request	`importDashboardData`	`application/json`
Uploaded export file	`importDashboardDataFile`	`multipart/form-data`

For JSON requests, pass the exported dashboard’s data object as importDashboardData. For multipart requests, upload the complete export JSON file, including its top-level data object, as importDashboardDataFile. If both fields are supplied, the uploaded file takes precedence.

Client scope during import

The destination clientId determines the client scope of an imported client dashboard.

Scenario	Result
Client `102` metric imported into Client `103` with cross-tenant import enabled	Metric is imported and scoped to Client `103`
Same import with cross-tenant import disabled	Client `102` metric is skipped
Admin-created metric	Remains available to all clients unless it already has an explicit client filter
New metric created in the imported dashboard	Scoped to the destination client
Legacy exported client metric	Client ownership is inferred and scoped to the destination client
All-client or database tenancy	No automatic table-level client scope is added

Dashboard cards, fullscreen data, underlying data, CSV and raw-data downloads, and dashboard downloads all use the same destination-client scope. Imported client dashboards require client-scoped dashboard and metric filter options. Databrain hides automatic system client filters from users while keeping ordinary user-created filters visible and editable when permitted.

End users can view and use existing Custom SQL metrics and select values in saved filters, but cannot edit Custom SQL metrics or submit dashboard or metric filter definitions containing Custom SQL. Later end-user edit requests return HTTP 403 for these changes, even when metric update or end-user filter permissions are enabled. Author SQL changes in the workspace as an administrator. If your goal is a dashboard in your own workspace rather than a client embed, use the Import Dashboard API.

Response

string

The ID of the created dashboard embed configuration.

null | object

Error object if the request failed, otherwise null.

string

The name of the embed configuration. Matches the request body name if provided, otherwise the dashboardId. Returned by the new endpoint (/api/v2/data-app/dashboard-embeds); the legacy endpoint returns only id and error.

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
`INVALID_REQUEST_BODY`	Request body validation failed	400
`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
`INVALID_DASHBOARD_DATA`	Uploaded JSON missing `data`	400
`DASHBOARD_CREATE_ERROR`	Failed to create the client dashboard, or the import source is outside the same company and data app	400
`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,
      "joinModel": "multi",
      "metricCreationMode": "DRAG_DROP"
    }
  }'

(Optional) Use a template

To clone settings from an existing dashboard, add templateDashboardId. To also import metrics from the template, set isImportMetrics: true and optionally metricImportMode to "GALLERY" or "METRIC". To use a custom display name for the dashboard (instead of {dashboardId}_{clientId}), set name and isRenameDashboard: true:

{
  "dashboardId": "client-acme-analytics",
  "clientId": "acme-corp-123",
  "templateDashboardId": "template-dashboard-001",
  "name": "ACME Analytics Dashboard",
  "isRenameDashboard": true,
  "isImportMetrics": true,
  "metricImportMode": "GALLERY",
  "accessSettings": { ... }
}

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.

Custom Dashboard Names

Set isRenameDashboard: true with name to give each client dashboard a human-readable display name instead of {dashboardId}_{clientId}.

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

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Create a Dashboard Embed

Endpoint Formats

Authentication

Headers

Request Body

Dashboard import formats

Client scope during import

Response

HTTP Status Code Summary

Possible Errors

Quick Start Guide

Use Cases

Multi-Tenant SaaS

Template-Based Creation

Custom Dashboard Names

Dynamic Provisioning

Client Isolation

Next Steps

Generate Guest Token

Embed a Pre-built Dashboard/Metric

How to Embed

Multi-Tenant Access Control