> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed a Pre-built Dashboard/Metric

> Create an embed for an existing dashboard or metric that was built by your data analyst.

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.

<Warning>
  **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.
</Warning>

<Note>
  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](/developer-docs/helpers/api-reference/create-dashboard-embed) endpoint instead.
</Note>

## Endpoint Formats

<Tabs>
  <Tab title="New Endpoint (Recommended)">
    ```
    POST https://api.usedatabrain.com/api/v2/data-app/embeds
    ```

    **Use this endpoint** for all new integrations. This is the recommended endpoint format.
  </Tab>

  <Tab title="Legacy Endpoint (Deprecated Soon)">
    ```
    POST https://api.usedatabrain.com/api/v2/dataApp/embeds
    ```

    This endpoint still works but will be deprecated. Please migrate to the new endpoint format.
  </Tab>
</Tabs>

## 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](/guides/datasources/create-a-data-app) for details.

**Finding your API token:** For detailed instructions, see the [API Token guide](/developer-docs/helpers/api-token).

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your API key from the data app.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json` for all requests.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Request Body

<ParamField body="dashboardId" type="string" required>
  Existing dashboard ID to embed. This dashboard must already exist in your workspace.
</ParamField>

<ParamField body="embedType" type="'dashboard' | 'metric'" required>
  Type of embed configuration: `dashboard` or `metric`.
</ParamField>

<ParamField body="metricId" type="string">
  Metric ID to embed. Required if embedType is `metric`.
</ParamField>

<ParamField body="workspaceName" type="string" required>
  The name of the workspace where the embed configuration will be created.
</ParamField>

<ParamField body="name" type="string">
  Optional human-readable name for the embed configuration. If not provided, the embed ID will be used as the name.
</ParamField>

<ParamField body="accessSettings" type="object">
  Access control settings for the embedded view. Required when `embedType` is `dashboard`. Optional when `embedType` is `metric`.
</ParamField>

<ParamField body="accessSettings.datamartName" type="string" required>
  The datamart name used in the embedded environment. Required when `embedType` is `dashboard`.
</ParamField>

<ParamField body="accessSettings.isAllowAiPilot" type="boolean">
  Allow AI Pilot features (optional).
</ParamField>

<ParamField body="accessSettings.isAllowEmailReports" type="boolean" required>
  Allow sending email reports.
</ParamField>

<ParamField body="accessSettings.isAllowManageMetrics" type="boolean" required>
  Allow managing metrics.
</ParamField>

<ParamField body="accessSettings.isAllowCreateDashboardView" type="boolean" required>
  Allow creating dashboard views.
</ParamField>

<ParamField body="accessSettings.isAllowEndUserDashboardFilter" type="boolean">
  Optional. Enables end-user dashboard filter interactions in embedded mode.
</ParamField>

<ParamField body="accessSettings.dashboardFilterColumns" type="array">
  Optional allowlist for dashboard filterable columns. Each item must include `tableName` and `columns`.
</ParamField>

<ParamField body="accessSettings.dashboardFilterColumns[].tableName" type="string" required>
  Fully qualified table name used in dashboard filters.
</ParamField>

<ParamField body="accessSettings.dashboardFilterColumns[].columns" type="array[string]" required>
  Column names allowed for dashboard filter evaluation for the specified table.
</ParamField>

<ParamField body="accessSettings.isAllowMetricCreation" type="boolean" required>
  Allow metric creation.
</ParamField>

<ParamField body="accessSettings.isAllowMetricDeletion" type="boolean" required>
  Allow metric deletion.
</ParamField>

<ParamField body="accessSettings.isAllowMetricLayoutChange" type="boolean" required>
  Allow metric layout changes.
</ParamField>

<ParamField body="accessSettings.isAllowMetricUpdate" type="boolean" required>
  Allow updating metrics.
</ParamField>

<ParamField body="accessSettings.isAllowUnderlyingData" type="boolean" required>
  Allow viewing underlying data.
</ParamField>

<ParamField body="accessSettings.joinModel" type="'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)
</ParamField>

<ParamField body="accessSettings.isIncrementalJoin" type="boolean">
  Legacy join strategy flag. Prefer using `accessSettings.joinModel` instead.
</ParamField>

<ParamField body="accessSettings.metricCreationMode" type="'DRAG_DROP' | 'CHAT'" required>
  Mode of metric creation (drag and drop or chat).
</ParamField>

<ParamField body="accessSettings.tableTenancySettings" type="array">
  Multi-tenant table access configuration (optional).
</ParamField>

<ParamField body="accessSettings.tableTenancySettings[].name" type="string">
  Table name for tenancy configuration. Required when `tableTenancySettings` is provided.
</ParamField>

<ParamField body="accessSettings.tableTenancySettings[].clientColumn" type="string">
  Column name for client-level filtering. Required when `tableTenancySettings` is provided.
</ParamField>

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    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"
            }
          ]
        }
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    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);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    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']}")
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success Response theme={"dark"}
    {
      "id": "embed_abc123def456",
      "error": null
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_WORKSPACE_NAME",
        "message": "Invalid workspace name",
        "status": 400
      }
    }
    ```

    ```json Error Response (404) theme={"dark"}
    {
      "error": {
        "code": "INVALID_DASHBOARD_ID",
        "message": "Dashboard not found",
        "status": 404
      }
    }
    ```
  </ResponseExample>
</Panel>

## Response

<ResponseField name="id" type="string">
  Unique identifier for the created embed configuration.
</ResponseField>

<ResponseField name="error" type="null | object">
  Error object if the request failed, otherwise `null`.
</ResponseField>

## 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

<Steps>
  <Step title="Get your API token">
    For detailed instructions, see the [API Token guide](/developer-docs/helpers/api-token).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Create embed configuration for dashboard">
    Make a POST request to embed your existing dashboard:

    ```bash theme={"dark"}
    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"
        }
      }'
    ```
  </Step>

  <Step title="(Optional) Embed a single metric">
    To embed just one metric instead of the entire dashboard, use `embedType: "metric"`:

    ```json theme={"dark"}
    {
      "dashboardId": "existing-dashboard-id",
      "embedType": "metric",
      "metricId": "metric-123",
      "workspaceName": "my-workspace",
      // ... accessSettings
    }
    ```
  </Step>

  <Step title="Generate a guest token">
    Use the embed ID to generate a guest token for your end users. See the [Guest Token API](/developer-docs/helpers/api-reference/token) for details.
  </Step>

  <Step title="Embed in your application">
    Use the embed ID and guest token in your web component:

    ```javascript theme={"dark"}
    <dbn-dashboard 
      token="guest-token-here" 
      dashboard-id="existing-dashboard-id" 
    />
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Generate Guest Token" icon="key" href="/developer-docs/helpers/api-reference/token">
    Create secure tokens for your embed configurations
  </Card>

  <Card title="Create an Empty Dashboard" icon="plus" href="/developer-docs/helpers/api-reference/create-dashboard-embed">
    Create new empty dashboards for multi-tenant scenarios
  </Card>

  <Card title="Update Embed Config" icon="edit" href="/developer-docs/helpers/api-reference/update-embed">
    Modify existing embed configurations
  </Card>

  <Card title="How to Embed" icon="code" href="/developer-docs/how-to-embed">
    Learn how to integrate embeds in your application
  </Card>
</CardGroup>