Skip to Content

Workspace APIs

Update a workspace

Change a workspace's connection, AI settings or theme.

PUT
/api/v2/workspace
curl --request PUT 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 v2",    "themeName": "Acme light"  }'

Auth

A service token. See Authentication.

Authorization

ApiToken
headerAuthorizationBearer <token>

A service token or a data app API token.

Body

The fields are the same as Create a workspace. These rules are different:

  • name picks the workspace. You cannot rename it.
  • connectionType is required on every call, and the connection is set again each time. To keep it, send the same type and name.
  • A change to a DATASOURCE or DATAMART connection also moves the metrics on the workspace's dashboards to the new connection. Metrics on no dashboard are not moved. Multi workspaces move no metrics.
  • A new llmName clears the chosen model of the old LLM.
  • aiCopilotLlms: [] changes nothing.
  • The other fields change only when you send them.
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.

themeNamestring

Name of a theme in Settings > UI Theming.

Response

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

If name is "", the update was not saved. List the workspace and try again.

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYA field is missing, unknown or wrong
400WORKSPACE_DOES_NOT_EXISTNo workspace has this name
400INVALID_DATASOURCE_NAME or INVALID_DATAMART_NAMEThe connection name is unknown
400INVALID_LLM_NAME or INVALID_AI_COPILOT_LLMSAn LLM name is unknown
400INVALID_THEME_NAMENo theme has this name. The other changes were saved
500INTERNAL_SERVER_ERRORThe update failed

For errors that every endpoint returns, see Authentication.

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