Delete an Embed

curl --request DELETE \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "id": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "INVALID_REQUEST_BODY": "<string>",
  "INVALID_DATA_APP_API_KEY": "<string>",
  "INTERNAL_SERVER_ERROR": "<string>"
}

DELETE

api

data-app

embeds

curl --request DELETE \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "id": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "INVALID_REQUEST_BODY": "<string>",
  "INVALID_DATA_APP_API_KEY": "<string>",
  "INTERNAL_SERVER_ERROR": "<string>"
}

Permanently delete an embed from your data app. This will remove the embed and invalidate any associated guest tokens.

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.

This action is irreversible. Once an embed configuration is deleted, all associated guest tokens will become invalid and embedded dashboards will stop working.

Endpoint Formats

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

DELETE https://api.usedatabrain.com/api/v2/data-app/embeds?embedId={id}

Use this endpoint for all new integrations. This is the recommended endpoint format.

POST https://api.usedatabrain.com/api/v2/data-app/embeds?embedId={id}
Content-Type: application/json

{
  "embedId": "embed_abc123def456"
}

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

Query Parameters

string

required

The unique identifier of the embed configuration to delete. 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

string

Optional parameter to also delete the associated dashboard along with the embed configuration. Set to "true" to enable dashboard deletion.

Destructive Operation: When set to "true", this will permanently delete the dashboard associated with this embed. This action cannot be undone.

Show Dashboard deletion behavior

When dashboard deletion is allowed:

Dashboard was created via API.
Dashboard is only referenced by this single embed
Embed and dashboard both belong to your organization

Params:

isDeleteDashboard=true - Delete both embed and dashboard
isDeleteDashboard=false or omitted - Delete only embed configuration

Response

string

The ID of the deleted embed configuration for confirmation.

object

Error object returned only when the request fails. Not included in successful responses.

Show error properties

string

Error code identifying the type of error.

string

Human-readable error message describing what went wrong.

Examples

Legacy Endpoint Examples

The following examples use the deprecated POST endpoint. These are provided for reference only. Please use the DELETE endpoint examples above for all new integrations.

Error Codes

string

Invalid request body - Check that embedId is provided and valid

string

Missing or invalid data app - Check your API key and data app configuration

string

Unexpected failure - Internal server error occurred

HTTP Status Code Summary

Status Code	Description
200	OK - Embed deleted successfully
400	Bad Request - Invalid request parameters or embed not found
500	Internal Server Error - Unexpected server error

Possible Errors

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	500	Embed not found
`INVALID_REQUEST_BODY`	500	Internal dashboards can’t be removed
`INVALID_REQUEST_BODY`	500	Dashboard is referenced by multiple embeds
`INVALID_DATA_APP_API_KEY`	400	invalid or expired API KEY, data app not found

Usage Examples

Basic Deletion

// Delete an embed configuration
const result = await deleteEmbed({
  embedId: 'embed_123'
});
console.log(`Deleted embed: ${result.id}`);

Batch Deletion

// Delete multiple embed configurations
const embedIds = ['embed_1', 'embed_2', 'embed_3'];

for (const embedId of embedIds) {
  try {
    const result = await deleteEmbed({ embedId });
    console.log(`Deleted embed: ${result.id}`);
  } catch (error) {
    console.error(`Failed to delete ${embedId}:`, error.message);
  }
}

Safe Deletion with Verification

// Verify embed exists before deletion
const embeds = await listEmbeds();
const embedToDelete = embeds.data.find(e => e.embedId === 'embed_123');

if (embedToDelete) {
  const result = await deleteEmbed({
    embedId: embedToDelete.embedId
  });
  console.log(`Successfully deleted: ${result.id}`);
} else {
  console.log('Embed not found');
}

Best Practices

Verify Before Delete

Always verify the embed exists before attempting deletion

Handle Errors

Implement proper error handling for failed deletions

Update Documentation

Update your integration documentation after deletions

Monitor Impact

Monitor for any broken embedded dashboards after deletion

Important: Deleting an embed configuration will invalidate all guest tokens associated with it and break any embedded dashboards using this configuration. Ensure you have updated your application before deletion.

Next Steps

Embed a Pre-built Dashboard/Metric

Create new embed configurations to replace deleted ones

List All Embeds

View all remaining embed configurations

Update an Embed

Modify existing embed configurations instead of deleting

Guest Token API

Generate new tokens for your updated configurations

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

Endpoint Formats

Authentication

Headers

Query Parameters

Response

Examples

Legacy Endpoint Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Usage Examples

Basic Deletion

Batch Deletion

Safe Deletion with Verification

Best Practices

Verify Before Delete

Handle Errors

Update Documentation

Monitor Impact

Next Steps

Embed a Pre-built Dashboard/Metric

List All Embeds

Update an Embed

Guest Token API

​Endpoint Formats

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​Legacy Endpoint Examples

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Usage Examples

​Basic Deletion

​Batch Deletion

​Safe Deletion with Verification

​Best Practices

Verify Before Delete

Handle Errors

Update Documentation

Monitor Impact

​Next Steps

Embed a Pre-built Dashboard/Metric

List All Embeds

Update an Embed

Guest Token API

Endpoint Formats

Authentication

Headers

Query Parameters

Response

Examples

Legacy Endpoint Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Usage Examples

Basic Deletion

Batch Deletion

Safe Deletion with Verification

Best Practices

Next Steps