Skip to Content

Workspace APIs

Create a workspace

Make a workspace on a datasource or datamart, ready for dashboards and metrics.

POST
/api/v2/workspace
curl --request POST https://api.usedatabrain.com/api/v2/workspace \  --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \  --header "Content-Type: application/json" \  --data '{    "name": "Customer analytics",    "connectionType": "DATAMART",    "datamartName": "Sales"  }'

Auth

A service token. See Authentication.

Authorization

ApiToken
headerAuthorizationBearer <token>

A service token or a data app API token.

Body

Unknown fields are refused. Names are matched exactly, with capital letters.

namestringrequired

Up to 100 characters, unique in your organization. You cannot rename it with the API.

connectionTypestringrequired

DATASOURCE, DATAMART, MULTI_DATASOURCE or MULTI_DATAMART

Required for DATASOURCE. The datasource name. Ignored for other types.

Required for DATAMART. The datamart name. Ignored for other types.

llmNamestring

Name of an LLM in Settings > LLMs.

Names of the LLMs for the AI copilot.

Suggest metrics. Default false

AI summaries on metrics. Default false

Required with isEnableMetricSummary. technicalAndInsightSummary, forecastAndTrendAnalysis, comparativeAndAnomalyDetection or custom

Required with summaryType: custom. Your summary prompt.

Default: ""
themeNamestring

Name of a theme in Settings > UI Theming.

MULTI_DATASOURCE and MULTI_DATAMART workspaces have no fixed connection. Each guest token picks one with datasourceName or datamartName.

Response

{ "data": { "name": "Customer analytics" } }

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing, unknown or wrong
400WORKSPACE_NAME_ALREADY_EXISTSThe name is taken
400WORKSPACE_NAME_TOO_LONGThe name is over 100 characters
400INVALID_DATASOURCE_NAMENo datasource has this name
400INVALID_DATAMART_NAMENo datamart has this name
400INVALID_LLM_NAMENo LLM has this name
400INVALID_AI_COPILOT_LLMSOne of the aiCopilotLlms names is unknown
400INVALID_THEME_NAMENo theme has this name. The workspace was still created: set the theme with update
409limit_reachedYour plan's workspace limit is used. The body has limit, used, max, currentPlan and requiredPlan

For errors that every endpoint returns, see Authentication.

Next, create a data app.

Example Request
curl -X POST 'https://api.usedatabrain.com/api/v2/workspace' \  -H 'Content-Type: application/json' \  -d '{  "name": "Customer analytics",  "connectionType": "DATAMART",  "datamartName": "Sales"}'
Example Response
{  "data": {    "name": "Customer analytics"  }}