Update an Embed

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "embedId": "embed_abc123def456",
    "accessSettings": {
      "isAllowMetricCreation": false,
      "isAllowUnderlyingData": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    embedId: 'embed_abc123def456',
    accessSettings: {
      isAllowMetricCreation: false,
      isAllowUnderlyingData: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      joinModel: 'multi',
      tableTenancySettings: [
        {
          name: 'updated_sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Updated embed 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 = {
    "embedId": "embed_abc123def456",
    "accessSettings": {
        "isAllowMetricCreation": False,
        "isAllowUnderlyingData": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "joinModel": "multi",
        "tableTenancySettings": [
            {
                "name": "updated_sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

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

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

{
  "error": {
    "code": "EMBED_NOT_FOUND",
    "message": "Embed configuration not found",
    "status": 404,
    "details": {
      "embedId": "embed_invalid",
      "workspace": "analytics-workspace"
    }
  }
}

{
  "error": {
    "code": "INVALID_DATAMART",
    "message": "Specified datamart does not exist in workspace",
    "status": 400,
    "details": {
      "datamartName": "invalid-datamart",
      "workspace": "analytics-workspace"
    }
  }
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "embedId": "embed_abc123def456",
    "accessSettings": {
      "isAllowMetricCreation": false,
      "isAllowUnderlyingData": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    embedId: 'embed_abc123def456',
    accessSettings: {
      isAllowMetricCreation: false,
      isAllowUnderlyingData: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      joinModel: 'multi',
      tableTenancySettings: [
        {
          name: 'updated_sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Updated embed 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 = {
    "embedId": "embed_abc123def456",
    "accessSettings": {
        "isAllowMetricCreation": False,
        "isAllowUnderlyingData": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "joinModel": "multi",
        "tableTenancySettings": [
            {
                "name": "updated_sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

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

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

{
  "error": {
    "code": "EMBED_NOT_FOUND",
    "message": "Embed configuration not found",
    "status": 404,
    "details": {
      "embedId": "embed_invalid",
      "workspace": "analytics-workspace"
    }
  }
}

{
  "error": {
    "code": "INVALID_DATAMART",
    "message": "Specified datamart does not exist in workspace",
    "status": 400,
    "details": {
      "datamartName": "invalid-datamart",
      "workspace": "analytics-workspace"
    }
  }
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "embedId": "embed_abc123def456",
    "accessSettings": {
      "isAllowMetricCreation": false,
      "isAllowUnderlyingData": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    embedId: 'embed_abc123def456',
    accessSettings: {
      isAllowMetricCreation: false,
      isAllowUnderlyingData: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      joinModel: 'multi',
      tableTenancySettings: [
        {
          name: 'updated_sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Updated embed 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 = {
    "embedId": "embed_abc123def456",
    "accessSettings": {
        "isAllowMetricCreation": False,
        "isAllowUnderlyingData": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "joinModel": "multi",
        "tableTenancySettings": [
            {
                "name": "updated_sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

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

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

{
  "error": {
    "code": "EMBED_NOT_FOUND",
    "message": "Embed configuration not found",
    "status": 404,
    "details": {
      "embedId": "embed_invalid",
      "workspace": "analytics-workspace"
    }
  }
}

{
  "error": {
    "code": "INVALID_DATAMART",
    "message": "Specified datamart does not exist in workspace",
    "status": 400,
    "details": {
      "datamartName": "invalid-datamart",
      "workspace": "analytics-workspace"
    }
  }
}

PUT

api

data-app

embeds

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "embedId": "embed_abc123def456",
    "accessSettings": {
      "isAllowMetricCreation": false,
      "isAllowUnderlyingData": true,
      "isAllowEndUserDashboardFilter": true,
      "dashboardFilterColumns": [
        {
          "tableName": "public.sales_data",
          "columns": ["customer_id", "region", "order_date"]
        }
      ],
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer dbn_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    embedId: 'embed_abc123def456',
    accessSettings: {
      isAllowMetricCreation: false,
      isAllowUnderlyingData: true,
      isAllowEndUserDashboardFilter: true,
      dashboardFilterColumns: [
        {
          tableName: 'public.sales_data',
          columns: ['customer_id', 'region', 'order_date']
        }
      ],
      joinModel: 'multi',
      tableTenancySettings: [
        {
          name: 'updated_sales_data',
          clientColumn: 'customer_id'
        }
      ]
    }
  })
});

const data = await response.json();
console.log('Updated embed 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 = {
    "embedId": "embed_abc123def456",
    "accessSettings": {
        "isAllowMetricCreation": False,
        "isAllowUnderlyingData": True,
        "isAllowEndUserDashboardFilter": True,
        "dashboardFilterColumns": [
            {
                "tableName": "public.sales_data",
                "columns": ["customer_id", "region", "order_date"]
            }
        ],
        "joinModel": "multi",
        "tableTenancySettings": [
            {
                "name": "updated_sales_data",
                "clientColumn": "customer_id"
            }
        ]
    }
}

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

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

{
  "error": {
    "code": "EMBED_NOT_FOUND",
    "message": "Embed configuration not found",
    "status": 404,
    "details": {
      "embedId": "embed_invalid",
      "workspace": "analytics-workspace"
    }
  }
}

{
  "error": {
    "code": "INVALID_DATAMART",
    "message": "Specified datamart does not exist in workspace",
    "status": 400,
    "details": {
      "datamartName": "invalid-datamart",
      "workspace": "analytics-workspace"
    }
  }
}

Modify existing embeds to update access settings, change permissions, or associate with different datamarts. This allows you to evolve your embedded analytics without recreating configurations.

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.

Updates to embed configurations take effect immediately for all active embedded dashboards and metrics using this configuration.

Endpoint Formats

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

PUT 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/embed/update
Content-Type: application/json

{
  "embedId": "embed_abc123def456",
  "accessSettings": { ... }
}

This endpoint still works but will be deprecated. Uses POST method with JSON body.

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

The unique identifier of the embed configuration to update. Get this from the create embed response or list embeds API.

Show Finding embed IDs

Use the List All Embeds API to get embed IDs
Check the response from embed creation
Available in the DataBrain dashboard when viewing embed configurations

object

required

Updated access control settings for the embedded view. Only provided fields will be updated.

string

Change the datamart used by this embed configuration.

boolean

Update AI Pilot permission.

boolean

Update email reports permission.

boolean

Update metrics management permission.

boolean

Update metric creation permission.

boolean

Update metric deletion permission.

boolean

Update metric layout change permission.

boolean

Update metric modification permission.

boolean

Update underlying data access permission.

boolean

Update dashboard view creation permission.

boolean

Optional. Enable or disable end-user dashboard filter interactions.

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.

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

Update the metric creation mode.

array

Update multi-tenant table access configuration.

string

Table name for tenancy configuration.

string

Column name for client-level filtering.

Response

string

The ID of the updated embed configuration.

null | object

Error object if the request failed, otherwise null for successful requests.

Examples

Error Codes

string

Embed configuration not found - The specified embed ID doesn’t exist in the workspace

string

Workspace not found - The specified workspace doesn’t exist or you don’t have access

string

Invalid datamart - The specified datamart doesn’t exist in the workspace

string

Insufficient permissions - You don’t have permission to update this embed configuration

string

Invalid API key - Check your API key in dashboard settings

HTTP Status Code Summary

Status Code	Description
`200`	OK - Embed configuration updated successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions to update
`404`	Not Found - Embed configuration not found
`409`	Conflict - Update conflicts with existing configuration
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description
`EMBED_NOT_FOUND`	404	Embed configuration not found
`INVALID_WORKSPACE_NAME`	404	Workspace not found
`INVALID_DATAMART`	404	Datamart not found
`INSUFFICIENT_PERMISSIONS`	403	No permission to update
`AUTHENTICATION_ERR`	401	Invalid API key
`INVALID_ACCESS_SETTINGS`	400	Invalid access settings
`CONFLICTING_UPDATE`	409	Update conflicts with existing config
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_SERVER_ERROR`	500	Server error

Update Strategies

Permission escalation

Gradually increase permissions based on user needs:

// Enable metric creation for power users
await updateEmbed({
  embedId: 'embed_123',
  accessSettings: {
    isAllowMetricCreation: true,
    metricCreationMode: 'CHAT'
  }
});

Datamart migration

Move embed to a different datamart:

await updateEmbed({
  embedId: 'embed_123',
  accessSettings: {
    datamartName: 'new-datamart'
  }
});

Security tightening

Reduce permissions when needed:

await updateEmbed({
  embedId: 'embed_123',
  accessSettings: {
    isAllowMetricDeletion: false,
    isAllowUnderlyingData: false
  }
});

Common Update Scenarios

Enable Advanced Features

// Upgrade basic embed to include AI features
await updateEmbed({
  embedId: 'embed_basic',
  accessSettings: {
    isAllowEmailReports: true,
    metricCreationMode: 'CHAT'
  }
});

Migrate to New Datamart

// Move embed to updated datamart
await updateEmbed({
  embedId: 'embed_old',
  accessSettings: {
    datamartName: 'updated-sales-data',
    tableTenancySettings: [
      {
        name: 'new_customer_table',
        clientColumn: 'tenant_id'
      }
    ]
  }
});

Temporary Permission Reduction

// Temporarily reduce permissions during maintenance
await updateEmbed({
  embedId: 'embed_maintenance',
  accessSettings: {
    isAllowMetricCreation: false,
    isAllowMetricUpdate: false,
    isAllowMetricDeletion: false
  }
});

Best Practices

Change Management

Document all configuration changes
Test updates in staging first
Notify stakeholders of permission changes
Maintain change history and rollback plans

Security

Follow principle of least privilege
Regular permission audits
Monitor for unauthorized changes
Validate datamart access before updates

Performance

Batch multiple updates when possible
Monitor embed performance after changes
Test with production data volumes
Update during low-usage periods

User Experience

Communicate feature changes to users
Provide training for new capabilities
Gradual rollout of new permissions
Collect feedback on configuration changes

Advanced Configuration

Dynamic Permission Updates

// Update permissions based on user tier
const updatePermissionsForTier = async (embedId, userTier) => {
  const permissions = {
    basic: {
      isAllowMetricCreation: false,
      isAllowUnderlyingData: false
    },
    premium: {
      isAllowMetricCreation: true,
      isAllowUnderlyingData: true,
      metricCreationMode: 'CHAT'
    }
  };
  
  await updateEmbed({
    embedId,
    accessSettings: permissions[userTier]
  });
};

Bulk Updates

// Update multiple embeds with same settings
const bulkUpdateEmbeds = async (embedIds, updates) => {
  const promises = embedIds.map(embedId => 
    updateEmbed({
      embedId,
      accessSettings: updates
    })
  );
  
  const results = await Promise.all(promises);
  return results;
};

Quick Start Guide

Find your embed ID

List your existing embed configurations to find the one you want to update:

curl --request GET \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...'

Update specific permissions

Update only the settings you want to change. For example, to enable End User Metric Creation:

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "embedId": "embed_abc123def456",
    "accessSettings": {
      "isAllowMetricCreation": true
    }
  }'

Migrate to new datamart

Change the datamart associated with your embed:

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "embedId": "embed_abc123def456",
    "accessSettings": {
      "datamartName": "new-datamart-name"
    }
  }'

Verify the update

The API will return the embed ID on success:

const updateResult = await updateEmbed({
  embedId: 'embed_123',
  accessSettings: { isAllowMetricCreation: true }
});

console.log('Updated embed ID:', updateResult.id);
console.log('Success:', !updateResult.error);

Next Steps

Delete Embed Config

Remove embed configurations you no longer need

List All Embeds

View all embed configurations in your workspace

Generate Guest Token

Create tokens for your updated embed configurations

How to Embed

Learn the basics of embedding DataBrain

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Endpoint Formats

Authentication

Headers

Request Body

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Update Strategies

Common Update Scenarios

Enable Advanced Features

Migrate to New Datamart

Temporary Permission Reduction

Best Practices

Change Management

Security

Performance

User Experience

Advanced Configuration

Dynamic Permission Updates

Bulk Updates

Quick Start Guide

Next Steps

Delete Embed Config

List All Embeds

Generate Guest Token

How to Embed

​Endpoint Formats

​Authentication

​Headers

​Request Body

​Response

​Examples

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Update Strategies

​Common Update Scenarios

​Enable Advanced Features

​Migrate to New Datamart

​Temporary Permission Reduction

​Best Practices

Change Management

Security

Performance

User Experience

​Advanced Configuration

​Dynamic Permission Updates

​Bulk Updates

​Quick Start Guide

​Next Steps

Delete Embed Config

List All Embeds

Generate Guest Token

How to Embed

Endpoint Formats

Authentication

Headers

Request Body

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Update Strategies

Common Update Scenarios

Enable Advanced Features

Migrate to New Datamart

Temporary Permission Reduction

Best Practices

Advanced Configuration

Dynamic Permission Updates

Bulk Updates

Quick Start Guide

Next Steps