Update Workspace - Databrain

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/workspace \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Sales Analytics",
    "connectionType": "DATASOURCE",
    "datasourceName": "postgres-production"
  }'

{
  "data": {
    "name": "Sales Analytics"
  },
  "error": null
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/workspace \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Sales Analytics",
    "connectionType": "DATASOURCE",
    "datasourceName": "postgres-production"
  }'

{
  "data": {
    "name": "Sales Analytics"
  },
  "error": null
}

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/workspace \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Sales Analytics",
    "connectionType": "DATASOURCE",
    "datasourceName": "postgres-production"
  }'

{
  "data": {
    "name": "Sales Analytics"
  },
  "error": null
}

PUT

api

workspace

curl --request PUT \
  --url https://api.usedatabrain.com/api/v2/workspace \
  --header 'Authorization: Bearer dbn_live_abc123...' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Sales Analytics",
    "connectionType": "DATASOURCE",
    "datasourceName": "postgres-production"
  }'

{
  "data": {
    "name": "Sales Analytics"
  },
  "error": null
}

Update the connection settings of an existing workspace. You can switch between datasource, datamart, multi-datasource, and multi-datamart configurations. Updating a workspace also updates all associated metrics to use the new connection.

Important: Updating a workspace connection will automatically update all metrics in that workspace to use the new datasource or datamart connection. Ensure the new connection has compatible table and column structures to avoid breaking existing metrics.

The workspace name is used to identify which workspace to update and cannot be changed through this endpoint. To rename a workspace, you’ll need to create a new one and migrate your content.

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:

In Settings page, navigate to the Service Tokens section.
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...

Content-Type

string

required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

name

string

required

Name of the existing workspace to update. Must match exactly (case-sensitive).

Show Finding workspace names

Use the List Workspaces API to get all workspace names
Names are case-sensitive and must match exactly
This field identifies which workspace to update

connectionType

string

required

New connection type for the workspace. Must be one of: DATASOURCE, DATAMART, MULTI_DATASOURCE, or MULTI_DATAMART.

Show Connection type details

DATASOURCE: Connect directly to a single datasource
DATAMART: Connect to a pre-configured datamart
MULTI_DATASOURCE: Allow connections to multiple datasources within this workspace
MULTI_DATAMART: Allow switching between multiple datamarts within this workspace

Note: Changing connection type will update all metrics in this workspace. For MULTI_DATASOURCE or MULTI_DATAMART, datasourceName and datamartName are optional; the API clears prior single-datasource or single-datamart links and enables the selected multi mode. For DATASOURCE or DATAMART, datasourceName or datamartName is required (respectively), and multi-datasource / multi-datamart modes are turned off.

datasourceName

string

Name of the datasource to connect to this workspace.Required when connectionType is DATASOURCE.

Show Datasource considerations

Must be an existing datasource in your organization
Use the exact name as stored in datasource credentials
Names are case-sensitive
All metrics will be updated to use this datasource

datamartName

string

Name of the datamart to connect to this workspace.Required when connectionType is DATAMART.

Show Datamart considerations

Must be an existing datamart in your organization
Use the List Datamarts API to find available datamarts
Names are case-sensitive
All metrics will be updated to use this datamart’s datasource

llmName

string

Optional primary LLM name for workspace-level AI features. Must match an existing LLM configured in your organization.

aiCopilotLlms

array

Optional list of LLM names available for AI Copilot in this workspace. Every value must match an existing organization LLM name.

isEnableMetricSuggestions

boolean

Optional flag to enable or disable AI-powered metric suggestions for this workspace.

isEnableMetricSummary

boolean

Optional flag to enable or disable AI-generated metric summaries for this workspace.

summaryType

string

Summary mode used when metric summaries are enabled. Must be one of: technicalAndInsightSummary, forecastAndTrendAnalysis, comparativeAndAnomalyDetection, custom.Required when isEnableMetricSummary is true.

customSummaryPrompt

string

Custom summary instruction prompt for AI-generated summaries.Required when summaryType is custom.

themeName

string

Optional workspace theme name. Must match an existing theme configured in your organization.

Response

data

object

Contains the updated workspace information on success.

Show data properties

name

string

The name of the successfully updated workspace.

error

null | object

Error object if the request failed, otherwise null for successful requests.

Show error properties

code

string

Error code identifying the type of error.

message

string

Human-readable error message describing what went wrong.

Examples

HTTP Status Code Summary

Status Code	Description
`200`	OK - Workspace updated successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`500`	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description
`INVALID_REQUEST_BODY`	400	Missing or invalid parameters
`WORKSPACE_DOES_NOT_EXIST`	400	Workspace not found
`INVALID_DATASOURCE_NAME`	400	Datasource not found
`INVALID_DATAMART_NAME`	400	Datamart not found
`INVALID_LLM_NAME`	400	Invalid LLM name provided
`INVALID_AI_COPILOT_LLMS`	400	Invalid AI Copilot LLM list
`INVALID_THEME_NAME`	400	Invalid theme name provided
`INVALID_DATA_APP_API_KEY`	401	Invalid API key
`INTERNAL_SERVER_ERROR`	500	Server error

List Workspaces

Update Workspace Dashboards

Documentation Index

​Authentication

​Headers

​Request Body

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

Authentication

Headers

Request Body

Response

Examples

HTTP Status Code Summary

Possible Errors