Authentication
Datasource APIs
Semantic Layer APIs
Embeds
Data App APIs
Metric APIs
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
}
Workspace APIs
Update Workspace
Update an existing workspace’s connection settings to change datasource, datamart, multi-datasource, or multi-datamart configuration.
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
/
v2
/
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.
Headers
Bearer token for API authentication. Use your service token.
Authorization: Bearer dbn_live_abc123...
Must be set to
application/json for all requests.Content-Type: application/json
Request Body
Name of the existing workspace to update. Must match exactly (case-sensitive).
Show Finding workspace names
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
New connection type for the workspace. Must be one of:
DATASOURCE, DATAMART, MULTI_DATASOURCE, or MULTI_DATAMART.Show Connection type details
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
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.Name of the datasource to connect to this workspace.Required when
connectionType is DATASOURCE.Show Datasource considerations
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
Name of the datamart to connect to this workspace.Required when
connectionType is DATAMART.Show Datamart considerations
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
Optional primary LLM name for workspace-level AI features. Must match an existing LLM configured in your organization.
Optional list of LLM names available for AI Copilot in this workspace. Every value must match an existing organization LLM name.
Optional flag to enable or disable AI-powered metric suggestions for this workspace.
Optional flag to enable or disable AI-generated metric summaries for this workspace.
Summary mode used when metric summaries are enabled. Must be one of:
technicalAndInsightSummary, forecastAndTrendAnalysis, comparativeAndAnomalyDetection, custom.Required when isEnableMetricSummary is true.Custom summary instruction prompt for AI-generated summaries.Required when
summaryType is custom.Optional workspace theme name. Must match an existing theme configured in your organization.
Response
Contains the updated workspace information on success.
Show data properties
Show data properties
The name of the successfully updated workspace.
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 |
⌘I