Authentication
Datasource APIs
Embeds
Data App APIs
Metric APIs
Copy
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'
Copy
{
"id": "embed_abc123def456",
"error": null
}
Copy
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'
Copy
{
"id": "embed_abc123def456",
"error": null
}
Embeds
Delete an Embed
Delete an embed from your data app. This action cannot be undone.
Copy
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'
Copy
{
"id": "embed_abc123def456",
"error": null
}
DELETE
/
api
/
v2
/
data-app
/
embeds
Copy
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'
Copy
{
"id": "embed_abc123def456",
"error": null
}
Permanently delete an embed from your data app. This will remove the embed and invalidate any associated guest tokens.
Use this endpoint for all new integrations. This is the recommended endpoint format.This endpoint still works but will be deprecated. Uses POST method with JSON body.
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)
Copy
DELETE https://api.usedatabrain.com/api/v2/data-app/embeds?embedId={id}
Copy
POST https://api.usedatabrain.com/api/v2/data-app/embeds?embedId={id}
Content-Type: application/json
{
"embedId": "embed_abc123def456"
}
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
Bearer token for API authentication. Use your API key from the data app.
Copy
Authorization: Bearer dbn_live_abc123...
Query Parameters
The unique identifier of the embed configuration to delete. Get this from the create embed response or list embeds API.
Show Finding embed IDs
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
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
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
isDeleteDashboard=true- Delete both embed and dashboardisDeleteDashboard=falseor omitted - Delete only embed configuration
Response
The ID of the deleted embed configuration for confirmation.
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 - Check that embedId is provided and valid
Missing or invalid data app - Check your API key and data app configuration
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
Copy
// Delete an embed configuration
const result = await deleteEmbed({
embedId: 'embed_123'
});
console.log(`Deleted embed: ${result.id}`);
Batch Deletion
Copy
// 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
Copy
// 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
⌘I