Skip to main content
curl --request POST \
  --url 'https://api.usedatabrain.com/api/v2/dataApp/embed/delete' \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' 

{
  "id": "embed_abc123def456",
  "error": null
}
DELETE
https://api.usedatabrain.com
/
api
/
v2
/
data-app
/
embeds
curl --request POST \
  --url 'https://api.usedatabrain.com/api/v2/dataApp/embed/delete' \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' 

{
  "id": "embed_abc123def456",
  "error": null
}
Permanently delete an embed configuration from your data app. This will remove the embed configuration 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

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

​
Response

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

​
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 CodeDescription
200OK - Embed deleted successfully
400Bad Request - Invalid request parameters or embed not found
500Internal Server Error - Unexpected server error

​
Possible Errors

Error CodeHTTP StatusDescription
INVALID_REQUEST_BODY500Embed not found
INVALID_REQUEST_BODY500Internal dashboards can’t be removed
INVALID_REQUEST_BODY500Dashboard is referenced by multiple embeds
INVALID_DATA_APP_API_KEY400invalid 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

Create Embed Configuration

Create new embed configurations to replace deleted ones

List All Embeds

View all remaining embed configurations

Update Embed Configuration

Modify existing embed configurations instead of deleting

Guest Token API

Generate new tokens for your updated configurations