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

# Update an Embed

> Update an existing embed to modify access settings, permissions, and datamart associations.

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.

<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>
  Updates to embed configurations take effect immediately for all active embedded dashboards and metrics using this configuration.
</Note>

## Endpoint Formats

<Tabs>
  <Tab title="New Endpoint (Recommended)">
    ```
    PUT 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/embed/update
    Content-Type: application/json

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

    This endpoint still works but will be deprecated. Uses POST method with JSON body.
  </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).

<Panel>
  <RequestExample>
    ```bash Authentication theme={"dark"}
    curl --request PUT \
      --url https://api.usedatabrain.com/api/v2/data-app/embeds \
      --header 'Authorization: Bearer dbn_live_...' \
      --header 'Content-Type: application/json'
    ```
  </RequestExample>
</Panel>

## 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="embedId" type="string" required>
  The unique identifier of the embed configuration to update. Get this from the create embed response or list embeds API.

  <Expandable title="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
  </Expandable>
</ParamField>

<ParamField body="accessSettings" type="object" required>
  Updated access control settings for the embedded view. Only provided fields will be updated.

  <ParamField body="accessSettings.datamartName" type="string">
    Change the datamart used by this embed configuration.
  </ParamField>

  <ParamField body="accessSettings.isAllowAiPilot" type="boolean">
    Update AI Pilot permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowEmailReports" type="boolean">
    Update email reports permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowManageMetrics" type="boolean">
    Update metrics management permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowMetricCreation" type="boolean">
    Update metric creation permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowMetricDeletion" type="boolean">
    Update metric deletion permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowMetricLayoutChange" type="boolean">
    Update metric layout change permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowMetricUpdate" type="boolean">
    Update metric modification permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowUnderlyingData" type="boolean">
    Update underlying data access permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowCreateDashboardView" type="boolean">
    Update dashboard view creation permission.
  </ParamField>

  <ParamField body="accessSettings.isAllowEndUserDashboardFilter" type="boolean">
    Optional. Enable or disable end-user dashboard filter interactions.
  </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.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'">
    Update the metric creation mode.
  </ParamField>

  <ParamField body="accessSettings.tableTenancySettings" type="array">
    Update multi-tenant table access configuration.

    <ParamField body="accessSettings.tableTenancySettings[].name" type="string">
      Table name for tenancy configuration.
    </ParamField>

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

## Response

<ResponseField name="id" type="string">
  The ID of the updated embed configuration.
</ResponseField>

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

## Examples

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

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

    ```python 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 = {
        "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']}")
    ```
  </RequestExample>

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

    ```json Error Response (404) theme={"dark"}
    {
      "error": {
        "code": "EMBED_NOT_FOUND",
        "message": "Embed configuration not found",
        "status": 404,
        "details": {
          "embedId": "embed_invalid",
          "workspace": "analytics-workspace"
        }
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATAMART",
        "message": "Specified datamart does not exist in workspace",
        "status": 400,
        "details": {
          "datamartName": "invalid-datamart",
          "workspace": "analytics-workspace"
        }
      }
    }
    ```
  </ResponseExample>
</Panel>

## Error Codes

<ResponseField name="EMBED_NOT_FOUND" type="string">
  **Embed configuration not found** - The specified embed ID doesn't exist in the workspace
</ResponseField>

<ResponseField name="INVALID_WORKSPACE_NAME" type="string">
  **Workspace not found** - The specified workspace doesn't exist or you don't have access
</ResponseField>

<ResponseField name="INVALID_DATAMART" type="string">
  **Invalid datamart** - The specified datamart doesn't exist in the workspace
</ResponseField>

<ResponseField name="INSUFFICIENT_PERMISSIONS" type="string">
  **Insufficient permissions** - You don't have permission to update this embed configuration
</ResponseField>

<ResponseField name="AUTHENTICATION_ERR" type="string">
  **Invalid API key** - Check your API key in dashboard settings
</ResponseField>

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

<Steps>
  <Step title="Permission escalation">
    Gradually increase permissions based on user needs:

    ```javascript theme={"dark"}
    // Enable metric creation for power users
    await updateEmbed({
      embedId: 'embed_123',
      accessSettings: {
        isAllowMetricCreation: true,
        metricCreationMode: 'CHAT'
      }
    });
    ```
  </Step>

  <Step title="Datamart migration">
    Move embed to a different datamart:

    ```javascript theme={"dark"}
    await updateEmbed({
      embedId: 'embed_123',
      accessSettings: {
        datamartName: 'new-datamart'
      }
    });
    ```
  </Step>

  <Step title="Security tightening">
    Reduce permissions when needed:

    ```javascript theme={"dark"}
    await updateEmbed({
      embedId: 'embed_123',
      accessSettings: {
        isAllowMetricDeletion: false,
        isAllowUnderlyingData: false
      }
    });
    ```
  </Step>
</Steps>

## Common Update Scenarios

### Enable Advanced Features

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

### Migrate to New Datamart

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

```javascript theme={"dark"}
// Temporarily reduce permissions during maintenance
await updateEmbed({
  embedId: 'embed_maintenance',
  accessSettings: {
    isAllowMetricCreation: false,
    isAllowMetricUpdate: false,
    isAllowMetricDeletion: false
  }
});
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Change Management" icon="git-branch">
    * Document all configuration changes
    * Test updates in staging first
    * Notify stakeholders of permission changes
    * Maintain change history and rollback plans
  </Card>

  <Card title="Security" icon="shield-check">
    * Follow principle of least privilege
    * Regular permission audits
    * Monitor for unauthorized changes
    * Validate datamart access before updates
  </Card>

  <Card title="Performance" icon="bolt">
    * Batch multiple updates when possible
    * Monitor embed performance after changes
    * Test with production data volumes
    * Update during low-usage periods
  </Card>

  <Card title="User Experience" icon="user">
    * Communicate feature changes to users
    * Provide training for new capabilities
    * Gradual rollout of new permissions
    * Collect feedback on configuration changes
  </Card>
</CardGroup>

## Advanced Configuration

### Dynamic Permission Updates

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

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

<Steps>
  <Step title="Find your embed ID">
    List your existing embed configurations to find the one you want to update:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.usedatabrain.com/api/v2/data-app/embeds \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```
  </Step>

  <Step title="Update specific permissions">
    Update only the settings you want to change. For example, to enable End User Metric Creation:

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

  <Step title="Migrate to new datamart">
    Change the datamart associated with your embed:

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

  <Step title="Verify the update">
    The API will return the embed ID on success:

    ```javascript theme={"dark"}
    const updateResult = await updateEmbed({
      embedId: 'embed_123',
      accessSettings: { isAllowMetricCreation: true }
    });

    console.log('Updated embed ID:', updateResult.id);
    console.log('Success:', !updateResult.error);
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Delete Embed Config" icon="trash" href="/developer-docs/helpers/api-reference/delete-embed">
    Remove embed configurations you no longer need
  </Card>

  <Card title="List All Embeds" icon="list" href="/developer-docs/helpers/api-reference/list-embed">
    View all embed configurations in your workspace
  </Card>

  <Card title="Generate Guest Token" icon="key" href="/developer-docs/helpers/api-reference/token">
    Create tokens for your updated embed configurations
  </Card>

  <Card title="How to Embed" icon="book" href="/how-to-embed">
    Learn the basics of embedding DataBrain
  </Card>
</CardGroup>