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

# Delete an Embed

> Delete an embed from your data app. This action cannot be undone.

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

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

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

## Endpoint Formats

<Tabs>
  <Tab title="New Endpoint (Recommended)">
    ```
    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.
  </Tab>

  <Tab title="Legacy Endpoint (Deprecated Soon)">
    ```
    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.
  </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 DELETE \
      --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```
  </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>

## Query Parameters

<ParamField query="embedId" type="string" required>
  The unique identifier of the embed configuration to delete. 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 query="isDeleteDashboard" type="string">
  Optional parameter to also delete the associated dashboard along with the embed configuration. Set to `"true"` to enable dashboard deletion.

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

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

## Response

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

<ResponseField name="error" type="object">
  Error object returned only when the request fails. Not included in successful responses.

  <Expandable title="error properties">
    <ResponseField name="code" type="string">
      Error code identifying the type of error.
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message describing what went wrong.
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL - Delete Embed Only theme={"dark"}
    curl --request DELETE \
      --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

    ```bash cURL - Delete Embed and Dashboard theme={"dark"}
    curl --request DELETE \
      --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456&isDeleteDashboard=true' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

    ```javascript Node.js - Delete Embed Only icon="fa-brands fa-node-js" theme={"dark"}
    const embedId = 'embed_abc123def456';
    const response = await fetch(`https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=${encodeURIComponent(embedId)}`, {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...'
      }
    });

    const data = await response.json();
    console.log('Deleted embed:', data.id);
    ```

    ```javascript Node.js - Delete Embed and Dashboard icon="fa-brands fa-node-js" theme={"dark"}
    const embedId = 'embed_abc123def456';
    const isDeleteDashboard = true;

    const url = new URL('https://api.usedatabrain.com/api/v2/data-app/embeds');
    url.searchParams.append('embedId', embedId);
    url.searchParams.append('isDeleteDashboard', isDeleteDashboard.toString());

    const response = await fetch(url, {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...'
      }
    });

    const data = await response.json();
    console.log('Deleted embed and dashboard:', data.id);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/embeds"
    headers = {
        "Authorization": "Bearer dbn_live_abc123..."
    }
    params = {
        "embedId": "embed_abc123def456"
    }

    response = requests.delete(url, headers=headers, params=params)
    data = response.json()
    print(f"Deleted embed: {data['id']}")
    ```

    ```ruby Ruby icon="fa-solid fa-gem" theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/data-app/embeds')
    params = { embedId: 'embed_abc123def456' }
    uri.query = URI.encode_www_form(params)

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Delete.new(uri)
    request['Authorization'] = 'Bearer dbn_live_abc123...'

    response = http.request(request)
    data = JSON.parse(response.body)
    puts "Deleted embed: #{data['id']}"
    ```

    ```java Java icon="fa-brands fa-java" theme={"dark"}
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.net.URI;
    import java.net.URLEncoder;
    import java.nio.charset.StandardCharsets;

    public class DataBrainDeleteEmbedAPI {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            
            String embedId = URLEncoder.encode("embed_abc123def456", StandardCharsets.UTF_8);
            String url = String.format(
                "https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=%s",
                embedId
            );
            
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer dbn_live_abc123...")
                .DELETE()
                .build();
                
            HttpResponse<String> response = client.send(request, 
                HttpResponse.BodyHandlers.ofString());
                
            System.out.println("Response: " + response.body());
        }
    }
    ```

    ```go Go icon="fa-brands fa-golang" theme={"dark"}
    package main

    import (
        "encoding/json"
        "fmt"
        "net/http"
        "net/url"
    )

    type DeleteEmbedResponse struct {
        Id    string      `json:"id"`
        Error interface{} `json:"error"`
    }

    func main() {
        baseURL := "https://api.usedatabrain.com/api/v2/data-app/embeds"
        params := url.Values{}
        params.Add("embedId", "embed_abc123def456")
        
        fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())
        
        req, _ := http.NewRequest("DELETE", fullURL, nil)
        req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
        
        client := &http.Client{}
        resp, err := client.Do(req)
        if err != nil {
            panic(err)
        }
        defer resp.Body.Close()
        
        var embedResp DeleteEmbedResponse
        json.NewDecoder(resp.Body).Decode(&embedResp)
        
        fmt.Printf("Deleted embed: %s\n", embedResp.Id)
    }
    ```

    ```php PHP icon="fa-brands fa-php" theme={"dark"}
    <?php
    $params = http_build_query([
        'embedId' => 'embed_abc123def456'
    ]);

    $url = 'https://api.usedatabrain.com/api/v2/data-app/embeds?' . $params;

    $options = [
        'http' => [
            'header' => 'Authorization: Bearer dbn_live_abc123...',
            'method' => 'DELETE'
        ]
    ];

    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    $response = json_decode($result, true);

    echo "Deleted embed: " . $response['id'];
    ?>
    ```
  </RequestExample>

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

    ```json Error - Embed Not Found theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Embed not found"
      }
    }
    ```

    ```json Error - Internal Dashboard Cannot Be Deleted theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Deletion blocked: internal dashboards can't be removed."
      }
    }
    ```

    ```json Error - Dashboard Referenced by Multiple Embeds theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Deletion blocked: this dashboard is referenced by multiple embeds."
      }
    }
    ```

    ```json Error - Invalid API Key theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_API_KEY",
        "message": "invalid or expired API KEY, data app not found"
      }
    }
    ```
  </ResponseExample>
</Panel>

## Legacy Endpoint Examples

<Note>
  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.**
</Note>

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

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        embedId: 'embed_abc123def456'
      })
    });

    const data = await response.json();
    console.log('Deleted embed:', data.id);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456"
    headers = {
        "Authorization": "Bearer dbn_live_abc123...",
        "Content-Type": "application/json"
    }
    data = {
        "embedId": "embed_abc123def456"
    }

    response = requests.post(url, headers=headers, json=data)
    result = response.json()
    print(f"Deleted embed: {result['id']}")
    ```

    ```ruby Ruby icon="fa-solid fa-gem" theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456')
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(uri)
    request['Authorization'] = 'Bearer dbn_live_abc123...'
    request['Content-Type'] = 'application/json'
    request.body = {
      embedId: 'embed_abc123def456'
    }.to_json

    response = http.request(request)
    data = JSON.parse(response.body)
    puts "Deleted embed: #{data['id']}"
    ```

    ```java Java icon="fa-brands fa-java" theme={"dark"}
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.net.URI;

    public class DataBrainDeleteEmbedAPI {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            
            String requestBody = """
                {
                    "embedId": "embed_abc123def456"
                }""";
            
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456"))
                .header("Authorization", "Bearer dbn_live_abc123...")
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                .build();
                
            HttpResponse<String> response = client.send(request, 
                HttpResponse.BodyHandlers.ofString());
                
            System.out.println("Response: " + response.body());
        }
    }
    ```

    ```go Go icon="fa-brands fa-golang" theme={"dark"}
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "net/http"
    )

    type DeleteEmbedRequest struct {
        EmbedId string `json:"embedId"`
    }

    type DeleteEmbedResponse struct {
        Id    string      `json:"id"`
        Error interface{} `json:"error"`
    }

    func main() {
        reqData := DeleteEmbedRequest{
            EmbedId: "embed_abc123def456",
        }
        
        jsonData, _ := json.Marshal(reqData)
        
        req, _ := http.NewRequest("POST", "https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456", bytes.NewBuffer(jsonData))
        req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
        req.Header.Set("Content-Type", "application/json")
        
        client := &http.Client{}
        resp, err := client.Do(req)
        if err != nil {
            panic(err)
        }
        defer resp.Body.Close()
        
        var embedResp DeleteEmbedResponse
        json.NewDecoder(resp.Body).Decode(&embedResp)
        
        fmt.Printf("Deleted embed: %s\n", embedResp.Id)
    }
    ```

    ```php PHP icon="fa-brands fa-php" theme={"dark"}
    <?php
    $url = 'https://api.usedatabrain.com/api/v2/data-app/embeds?embedId=embed_abc123def456';
    $data = [
        'embedId' => 'embed_abc123def456'
    ];

    $options = [
        'http' => [
            'header' => [
                'Authorization: Bearer dbn_live_abc123...',
                'Content-Type: application/json'
            ],
            'method' => 'POST',
            'content' => json_encode($data)
        ]
    ];

    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    $response = json_decode($result, true);

    echo "Deleted embed: " . $response['id'];
    ?>
    ```
  </RequestExample>

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

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Embed not found",
        "status": 400
      }
    }
    ```
  </ResponseExample>
</Panel>

## Error Codes

<ResponseField name="INVALID_REQUEST_BODY" type="string">
  **Invalid request body** - Check that embedId is provided and valid
</ResponseField>

<ResponseField name="INVALID_DATA_APP_API_KEY" type="string">
  **Missing or invalid data app** - Check your API key and data app configuration
</ResponseField>

<ResponseField name="INTERNAL_SERVER_ERROR" type="string">
  **Unexpected failure** - Internal server error occurred
</ResponseField>

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

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

### Batch Deletion

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

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

<CardGroup cols={2}>
  <Card title="Verify Before Delete" icon="shield-check">
    Always verify the embed exists before attempting deletion
  </Card>

  <Card title="Handle Errors" icon="exclamation-triangle">
    Implement proper error handling for failed deletions
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Update Documentation" icon="book">
    Update your integration documentation after deletions
  </Card>

  <Card title="Monitor Impact" icon="chart-line">
    Monitor for any broken embedded dashboards after deletion
  </Card>
</CardGroup>

<Warning>
  **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.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Embed a Pre-built Dashboard/Metric" href="/developer-docs/helpers/api-reference/create-embed">
    Create new embed configurations to replace deleted ones
  </Card>

  <Card title="List All Embeds" href="/developer-docs/helpers/api-reference/list-embed">
    View all remaining embed configurations
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Update an Embed" href="/developer-docs/helpers/api-reference/update-embed">
    Modify existing embed configurations instead of deleting
  </Card>

  <Card title="Guest Token API" href="/developer-docs/helpers/api-reference/token">
    Generate new tokens for your updated configurations
  </Card>
</CardGroup>