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

> Delete the semantic layer from a datamart, removing all descriptions, synonyms, column types, and feedback.

Permanently remove all semantic layer metadata from a datamart. This clears table descriptions, column metadata (descriptions, synonyms, column types, configs), and feedback. The underlying datamart structure (tables, columns) remains intact.

<Danger>
  This action cannot be undone. All semantic metadata — descriptions, synonyms, column types, and feedback — will be permanently removed.
</Danger>

<Note>
  The datamart itself is not deleted. Only the semantic layer enrichments are removed. You can recreate the semantic layer using the [POST endpoint](/developer-docs/helpers/api-reference/create-semantic-layer).
</Note>

## Authentication

This endpoint requires a **service token** in the Authorization header. Data app API tokens are not permitted and will be rejected with a `403` error.

To access your service token:

1. Go to your Databrain dashboard and open **Settings**.
2. Navigate to **Settings**.
3. Find the **Service Tokens** section.
4. Click the **"Generate Token"** button to generate a new service token if you don't have one already.

Use this token as the Bearer value in your Authorization header.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your service token.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

## Query Parameters

<ParamField query="datamartName" type="string" required>
  The name of the datamart whose semantic layer you want to delete. Must match an existing datamart that has semantic data.

  <Expandable title="Finding datamart names">
    * Use the [List Datamarts API](/developer-docs/helpers/api-reference/list-datamarts) to get all datamart names
    * Use the [Get Semantic Layer API](/developer-docs/helpers/api-reference/get-semantic-layer) to confirm semantic data exists
  </Expandable>
</ParamField>

## Response

On success, the response body contains only the datamart name. There is no `error` field in the JSON body when the request succeeds.

<ResponseField name="id" type="string">
  The name of the datamart whose semantic layer was deleted.
</ResponseField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request DELETE \
      --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const datamartName = 'sales-analytics';
    const response = await fetch(
      `https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=${encodeURIComponent(datamartName)}`,
      {
        method: 'DELETE',
        headers: {
          'Authorization': 'Bearer dbn_live_abc123...'
        }
      }
    );

    const result = await response.json();

    if (result.error) {
      console.error('Delete failed:', result.error.message);
    } else {
      console.log('Semantic layer deleted for:', result.id);
    }
    ```

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

    response = requests.delete(
        'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer',
        headers={
            'Authorization': 'Bearer dbn_live_abc123...'
        },
        params={
            'datamartName': 'sales-analytics'
        }
    )

    result = response.json()

    if result.get('error'):
        print(f"Delete failed: {result['error']['message']}")
    else:
        print(f"Semantic layer deleted for: {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/datamarts/semantic-layer')
    params = { datamartName: 'sales-analytics' }
    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)
    result = JSON.parse(response.body)
    puts "Deleted: #{result['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 DeleteSemanticLayer {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();

            String datamartName = URLEncoder.encode("sales-analytics", StandardCharsets.UTF_8);
            String url = String.format(
                "https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=%s",
                datamartName
            );

            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.body());
        }
    }
    ```

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

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

    func main() {
        baseURL := "https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer"
        params := url.Values{}
        params.Add("datamartName", "sales-analytics")

        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, _ := client.Do(req)
        defer resp.Body.Close()

        var result map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&result)
        fmt.Printf("Deleted: %v\n", result["id"])
    }
    ```

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

    $url = 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?' . $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: " . $response['id'];
    ?>
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 - Success theme={"dark"}
    {
      "id": "sales-analytics"
    }
    ```

    ```json 400 - Missing datamartName theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "datamartName query parameter is required"
      }
    }
    ```

    ```json 400 - Datamart Not Found theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATAMART",
        "message": "Datamart 'nonexistent' not found"
      }
    }
    ```

    ```json 404 - No Semantic Layer theme={"dark"}
    {
      "error": {
        "code": "SEMANTIC_LAYER_NOT_FOUND",
        "message": "No semantic layer found for datamart 'sales-analytics'."
      }
    }
    ```

    ```json 403 - Data App Token theme={"dark"}
    {
      "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "Semantic Layer API requires a service token, not a data app API token"
      }
    }
    ```
  </ResponseExample>
</Panel>

## HTTP Status Code Summary

| Status Code | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `200`       | **OK** — Semantic layer deleted successfully                 |
| `400`       | **Bad Request** — Missing datamartName or datamart not found |
| `401`       | **Unauthorized** — Invalid or missing API token              |
| `403`       | **Forbidden** — Data app token used instead of service token |
| `404`       | **Not Found** — No semantic layer exists for this datamart   |
| `500`       | **Internal Server Error** — Server error occurred            |

## Possible Errors

| Error Code                 | HTTP Status | Description                                  |
| -------------------------- | ----------- | -------------------------------------------- |
| `INVALID_REQUEST_BODY`     | 400         | datamartName query parameter is missing      |
| `INVALID_DATAMART`         | 400         | Datamart not found                           |
| `SEMANTIC_LAYER_NOT_FOUND` | 404         | No semantic layer exists for this datamart   |
| `AUTHENTICATION_ERROR`     | 403         | Data app token used instead of service token |
| `INTERNAL_SERVER_ERROR`    | 500         | Server error                                 |

## Best Practices

<CardGroup cols={2}>
  <Card title="Backup First" icon="database">
    Use the GET endpoint to save a copy of the semantic layer before deleting
  </Card>

  <Card title="Check Dependencies" icon="link">
    AI chat mode relies on the semantic layer — verify impact before deleting
  </Card>
</CardGroup>

## Quick Start Guide

<Steps>
  <Step title="Backup the semantic layer">
    Retrieve and save the current semantic layer data:

    ```bash theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      -o semantic-layer-backup.json
    ```
  </Step>

  <Step title="Delete the semantic layer">
    ```bash theme={"dark"}
    curl --request DELETE \
      --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```
  </Step>

  <Step title="Verify deletion">
    Retrieve the datamart again to confirm the semantic layer was cleared:

    ```bash theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts/semantic-layer?datamartName=sales-analytics' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

    The response should show `null` descriptions, empty synonyms, and a completion score of `0`.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Semantic Layer" icon="plus" href="/developer-docs/helpers/api-reference/create-semantic-layer">
    Recreate the semantic layer with fresh metadata
  </Card>

  <Card title="Get Semantic Layer" icon="eye" href="/developer-docs/helpers/api-reference/get-semantic-layer">
    Verify the deletion
  </Card>

  <Card title="Semantic Layer Guide" icon="book" href="/guides/datasources/semantic-layer">
    Configure the semantic layer in the Databrain UI
  </Card>

  <Card title="List Datamarts" icon="list" href="/developer-docs/helpers/api-reference/list-datamarts">
    View your datamarts
  </Card>
</CardGroup>