Skip to main content
POST
Create workspaces to organize your analytics environment by connecting datasources or datamarts. Workspaces serve as containers for dashboards and metrics, providing structured access to your data.
Choose a connectionType that matches how this workspace will use data. For DATASOURCE or DATAMART, the corresponding datasourceName or datamartName must already exist in your organization. For MULTI_DATASOURCE or MULTI_DATAMART, those name fields are not required in the request body (see connectionType below).

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

string
required
Bearer token for API authentication. Use your service token.
string
required
Must be set to application/json for all requests.

Request Body

string
required
Name of the workspace to create. Must be unique within your organization.
string
required
Type of connection for the workspace. Must be one of: DATASOURCE, DATAMART, MULTI_DATASOURCE, or MULTI_DATAMART.
string
Name of the datasource to connect to this workspace.Required when connectionType is DATASOURCE.
string
Name of the datamart to connect to this workspace.Required when connectionType is DATAMART.
string
Optional primary LLM name for workspace-level AI features. Must match an existing LLM configured in your organization.
array
Optional list of LLM names available for AI Copilot in this workspace. Every value must match an existing organization LLM name.
boolean
Optional flag to enable AI-powered metric suggestions in this workspace. Defaults to false when omitted.
boolean
Optional flag to enable AI-generated metric summaries in this workspace. Defaults to false when omitted.
string
Summary mode used when metric summaries are enabled. Must be one of: technicalAndInsightSummary, forecastAndTrendAnalysis, comparativeAndAnomalyDetection, custom.Required when isEnableMetricSummary is true.
string
Custom summary instruction prompt for AI-generated summaries.Required when summaryType is custom.
string
Optional workspace theme name. Must match an existing theme configured in your organization.

Response

object
Contains the created workspace information on success.
null | object
Error object if the request failed, otherwise null for successful requests.

Examples

HTTP Status Code Summary

Possible Errors

Quick Start Guide

1

Verify prerequisites

Before creating a workspace, ensure you have:
  • A valid API token from your data app
  • Either a datasource or datamart already configured
  • The exact name of your datasource or datamart (case-sensitive)
2

Choose your connection type

Decide which connection type fits your use case:
  • DATASOURCE: For connecting to a single data source
  • DATAMART: For connecting to a pre-configured datamart with table/column configurations
  • MULTI_DATASOURCE: For workspaces that need access to multiple datasources
  • MULTI_DATAMART: For workspaces that support multiple datamarts (same API shape as multi-datasource: only name and connectionType in the minimal body)
Start with DATASOURCE for simple use cases. Use DATAMART when you need structured access with tenancy settings. For multi-datamart setup in the product UI, see Multi Datamart Workspace.
3

Create your workspace

Make the API call with your chosen configuration:
Successful response returns the workspace name. Save this for use in embed configurations.
4

Use your workspace

Reference your workspace in dashboards and metrics: