Delete an Embed - Databrain

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

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

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

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

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

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

DELETE

api

data-app

embeds

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

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

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

Authorization

string

required

Bearer token for API authentication. Use your API key from the data app.

Authorization: Bearer dbn_live_abc123...

Query Parameters

embedId

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

isDeleteDashboard

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.

error

object

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

Show error properties

code

string

Error code identifying the type of error.

message

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

INVALID_REQUEST_BODY

string

Invalid request body - Check that embedId is provided and valid

INVALID_DATA_APP_API_KEY

string

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

INTERNAL_SERVER_ERROR

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

Rename an Embed

Export Embedded Dashboard

​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