Skip to main content
curl --request DELETE \
  --url 'https://api.usedatabrain.com/api/v2/workspace?name=sales-analytics' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": {
    "id": "sales-analytics",
    "message": "Workspace deleted successfully"
  }
}
DELETE
/
api
/
v2
/
workspace
curl --request DELETE \
  --url 'https://api.usedatabrain.com/api/v2/workspace?name=sales-analytics' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": {
    "id": "sales-analytics",
    "message": "Workspace deleted successfully"
  }
}
Permanently delete a workspace. The workspace is identified by the name query parameter. The payload is validated with name: required string (Joi.string().required()).
This action is irreversible. Ensure no dashboards, metrics, or embeds still depend on this workspace before deleting it.

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

​
Headers

​
Authorization
string
required
Bearer token for API authentication. Use your service token.
Authorization: Bearer dbn_live_abc123...

​
Query Parameters

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

​
Response

On success, the API returns a top-level data object (same shape as other /api/v2/workspace handlers).
​
data
object
​
error
null | object
On success, error is omitted or null. On failure, contains code and message (see examples below).

​
Examples

​
HTTP Status Code Summary

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

​
Possible Errors

Error codeHTTP statusWhen it occurs
AUTHENTICATION_ERROR400Authorization missing or malformed (isPrivateApp middleware)
INVALID_REQUEST_BODY400deleteWorkspaceSchema validation failed (e.g. missing name)
WORKSPACE_ID_ERROR400No workspace with that name for your company
AUTHENTICATION_ERROR401Service token invalid, expired, or missing required scopes
INTERNAL_SERVER_ERROR500Delete mutation returned no row, GraphQL error, or handler catch

​
Next Steps

List Workspaces

List remaining workspaces in your organization

Create Workspace

Create a new workspace after deletion

Update Workspace

Update workspace settings instead of deleting