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

> Permanently delete a workspace from your organization by name.

Permanently delete a workspace. The workspace is identified by the **`name`** query parameter. The payload is validated with **`name`**: required string (`Joi.string().required()`).

<Danger>
  This action is irreversible. Ensure no dashboards, metrics, or embeds still depend on this workspace before deleting it.
</Danger>

## Endpoint

```
DELETE https://api.usedatabrain.com/api/v2/workspace?name={name}
```

## Self-hosted Databrain Endpoint

```
DELETE <SELF_HOSTED_URL>/api/v2/workspace?name={name}
```

## Authentication

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions.

To access your service token:

1. In **Settings** page, navigate to the **Service Tokens** section.
2. Click the **"Generate Token"** button to create a new service token if you don't have one already.

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

<Panel>
  <RequestExample>
    ```bash Authentication theme={"dark"}
    curl --request DELETE \
      --url 'https://api.usedatabrain.com/api/v2/workspace?name=sales-analytics' \
      --header 'Authorization: Bearer dbn_live_...'
    ```
  </RequestExample>
</Panel>

## 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="name" type="string" required>
  Workspace name to delete. Must match an existing workspace in your organization (case-sensitive, same string as returned by list/create).

  If `name` is omitted, validation fails with `INVALID_REQUEST_BODY` and the Joi validation message (for example `"name" is required`).

  <Expandable title="Finding workspace names">
    * Use the [List Workspaces API](/developer-docs/helpers/api-reference/list-workspaces) to list workspace names
    * Use the same value as in [Create Workspace](/developer-docs/helpers/api-reference/create-workspace) / [Update Workspace](/developer-docs/helpers/api-reference/update-workspace)
  </Expandable>
</ParamField>

## Response

On success, the API returns a top-level **`data`** object (same shape as other `/api/v2/workspace` handlers).

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      Set to the workspace **`name`** that was deleted (string echoed from the query parameter).
    </ResponseField>

    <ResponseField name="message" type="string">
      Success message: `Workspace deleted successfully`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="null | object">
  On success, `error` is omitted or null. On failure, contains `code` and `message` (see examples below).
</ResponseField>

## Examples

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

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

    const result = await response.json();
    if (result.error) {
      console.error('Error:', result.error);
    } else {
      console.log('Deleted workspace:', result.data);
    }
    ```

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

    url = "https://api.usedatabrain.com/api/v2/workspace"
    headers = {"Authorization": "Bearer dbn_live_abc123..."}
    params = {"name": "sales-analytics"}

    response = requests.delete(url, headers=headers, params=params)
    result = response.json()

    if result.get("error"):
        print("Error:", result["error"])
    else:
        print("Deleted workspace:", result.get("data"))
    ```
  </RequestExample>

  <ResponseExample>
    ```json 200 - Success theme={"dark"}
    {
      "data": {
        "id": "sales-analytics",
        "message": "Workspace deleted successfully"
      }
    }
    ```

    ```json 400 - Missing or invalid API key (middleware) theme={"dark"}
    {
      "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "API Key is not provided or Invalid!"
      }
    }
    ```

    ```json 400 - Invalid request body (Joi) theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "\"name\" is required"
      }
    }
    ```

    ```json 400 - Workspace not found theme={"dark"}
    {
      "error": {
        "code": "WORKSPACE_ID_ERROR",
        "message": "invalid workspace name, workspace name not found"
      }
    }
    ```

    ```json 401 - Invalid or expired API key (middleware) theme={"dark"}
    {
      "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "API Key is invalid or expired!"
      }
    }
    ```

    ```json 500 - Internal server error theme={"dark"}
    {
      "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "INTERNAL_SERVER_ERROR"
      }
    }
    ```
  </ResponseExample>
</Panel>

## HTTP Status Code Summary

| Status Code | Description                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `200`       | **OK** — Workspace deleted successfully                                                               |
| `400`       | **Bad Request** — Missing/invalid API key (middleware), Joi validation failed, or workspace not found |
| `401`       | **Unauthorized** — Invalid/expired token or missing required scopes (middleware)                      |
| `500`       | **Internal Server Error** — Delete mutation failed or unexpected error                                |

## Possible Errors

| Error code              | HTTP status | When it occurs                                                   |
| ----------------------- | ----------- | ---------------------------------------------------------------- |
| `AUTHENTICATION_ERROR`  | 400         | Authorization missing or malformed (`isPrivateApp` middleware)   |
| `INVALID_REQUEST_BODY`  | 400         | `deleteWorkspaceSchema` validation failed (e.g. missing `name`)  |
| `WORKSPACE_ID_ERROR`    | 400         | No workspace with that `name` for your company                   |
| `AUTHENTICATION_ERROR`  | 401         | Service token invalid, expired, or missing required scopes       |
| `INTERNAL_SERVER_ERROR` | 500         | Delete mutation returned no row, GraphQL error, or handler catch |

## Next Steps

<CardGroup cols={2}>
  <Card title="List Workspaces" icon="list" href="/developer-docs/helpers/api-reference/list-workspaces">
    List remaining workspaces in your organization
  </Card>

  <Card title="Create Workspace" icon="plus" href="/developer-docs/helpers/api-reference/create-workspace">
    Create a new workspace after deletion
  </Card>

  <Card title="Update Workspace" icon="edit" href="/developer-docs/helpers/api-reference/update-workspace">
    Update workspace settings instead of deleting
  </Card>
</CardGroup>