Create a workspace¶

Create a workspace on behalf of the current identity and return the new workspace ID.

HTTP
POST $CLOUDSIGMA_API_BASE/workspaces

Before you call this API¶

Configure the regional API endpoint and authentication.

Choose a name for the new workspace.

Set the operation-specific values used in the request:

$WORKSPACE_NAME: The name of the workspace to create, passed in the request body’s name field.

A workspace name cannot be empty. The service ignores leading and trailing whitespace in the name.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/workspaces" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'$WORKSPACE_NAME'"
  }'

Parameter reference

Request body

Parameter	Type	Required	Description
`name`	string	Yes	Name of the workspace to create.

Successful response¶

On success, the API returns 200. data.id is the new workspace ID.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "ws_01"
  }
}

Field reference

Response fields:

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.id`	string	ID of the new workspace.

Error response¶

Response example

JSON
{
  "code": "ErrWorkspaceAlreadyExists",
  "msg": "Workspace already exists",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status	Error code	Common cause	Recommended action
`400`	`ErrParamInvalid` or `INVALID_ARGUMENT`	`name` is missing, empty, or does not meet the requirements.	Provide a non-empty workspace name and retry.
`401`	`Unauthorized` or `UNAUTHENTICATED`	Credentials are missing or invalid.	Check the personal access token.
`403`	`ErrUserNotSynced` or `PERMISSION_DENIED`	The current identity has not been synchronized or cannot create workspaces.	Complete account synchronization, or ask an administrator for access before retrying.
`409`	`ErrWorkspaceCreating` or `ErrWorkspaceAlreadyExists`	A workspace with the same name is being created or already exists.	Wait for the pending creation to finish, or use another name.
`410`	`ErrWorkspaceRolledBack`	An earlier creation was rolled back.	Check the creation conditions and retry with a new request.
`500`	`ErrWorkspaceCreateFailed` or `ErrWorkspaceManualIntervention`	The service could not create the workspace.	Record the request time and error message, then contact an administrator.

Last updated on Sep 15, 2026