Update an Embed - Databrain

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,
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

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

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,
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

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

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,
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

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

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,
      "joinModel": "multi",
      "tableTenancySettings": [
        {
          "name": "updated_sales_data",
          "clientColumn": "customer_id"
        }
      ]
    }
  }'

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

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

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

embedId

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

accessSettings

object

required

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

accessSettings.datamartName

string

Change the datamart used by this embed configuration.

accessSettings.isAllowAiPilot

boolean

Update AI Pilot permission.

accessSettings.isAllowEmailReports

boolean

Update email reports permission.

accessSettings.isAllowManageMetrics

boolean

Update metrics management permission.

accessSettings.isAllowMetricCreation

boolean

Update metric creation permission.

accessSettings.isAllowMetricDeletion

boolean

Update metric deletion permission.

accessSettings.isAllowMetricLayoutChange

boolean

Update metric layout change permission.

accessSettings.isAllowMetricUpdate

boolean

Update metric modification permission.

accessSettings.isAllowUnderlyingData

boolean

Update underlying data access permission.

accessSettings.isAllowCreateDashboardView

boolean

Update dashboard view creation permission.

accessSettings.joinModel

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

accessSettings.isIncrementalJoin

boolean

Legacy join strategy flag. Prefer using accessSettings.joinModel instead.

accessSettings.metricCreationMode

'DRAG_DROP' | 'CHAT'

Update the metric creation mode.

accessSettings.tableTenancySettings

array

Update multi-tenant table access configuration.

accessSettings.tableTenancySettings[].name

string

Table name for tenancy configuration.

accessSettings.tableTenancySettings[].clientColumn

string

Column name for client-level filtering.

Response

string

The ID of the updated embed configuration.

error

null | object

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

Examples

Error Codes

EMBED_NOT_FOUND

string

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

INVALID_WORKSPACE_NAME

string

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

INVALID_DATAMART

string

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

INSUFFICIENT_PERMISSIONS

string

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

AUTHENTICATION_ERR

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

List Schedule Reports by Embed

Rename an 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