Updated on 2025-09-15 GMT+08:00

Creating a Workspace

Function

This API is used to create a workspace. You can use this API to create a workspace. You can input the name, description, MetaStore ID, enterprise project ID, and tag. The workspace details can be returned. This API is synchronous with no accompanying APIs. This API performs duplicate name verification and does not support creating workspaces with identical names. Additionally, there is an upper limit on the number of workspaces that can be created under the same account.

URI

POST /v1/workspaces

Request Parameters

Table 1 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

No

String

Definition: Tenant token. It is used for API calling authentication. For how to obtain a token, see [Authentication] (dataartsfabric_03_0005.xml).

Constraints: N/A.

Range: Up to 65,534 characters.

Default Value: N/A.

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

name

Yes

String

Definition: Workspace name.

Constraints: N/A.

Range: 4 to 32 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A.

description

No

String

Definition: Description entered by a user.

Constraints: N/A.

Range: 0 to 255 characters.

Default Value: N/A.

metastore_id

No

String

Definition: Instance ID of LakeFormation, that is, MetaStore ID.

Constraints: N/A.

Range: 32 to 36 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A.

enterprise_project_id

No

String

Definition: Enterprise project ID. For how to obtain an enterprise project ID, see [Obtaining an Enterprise Project ID] (dataartsfabric_03_0027.xml).

Constraints: This parameter can be set only when an enterprise project is connected.

Range: 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: 0, meaning the default ID is used.

tags

No

Array of ResourceTag objects

Definition: Resource tag.

Constraints: N/A.

Table 3 ResourceTag

Parameter

Mandatory

Type

Description

key

Yes

String

Definition: Resource tag key. For details about how to obtain a tag key, see "API Description" > "Resource Tags" > "Querying Tag Keys" in Tag Management Service API Reference.

Constraints: N/A.

Range: 1 to 128 characters. Only letters, spaces, tabs, digits, underscores (_), periods (.), colons (:), backslashes (), equal signs (=), plus signs (+), minus signs (-), and at signs (@) are allowed.

Default Value: N/A.

value

No

String

Definition: Resource tag value.

Constraints: N/A.

Range: 0 to 255 characters. Only letters, spaces, tabs, digits, underscores (_), periods (.), colons (:), backslashes (), equal signs (=), plus signs (+), minus signs (-), and at signs (@) are allowed.

Default Value: N/A.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

id

String

Definition: Workspace ID.

Constraints: N/A.

Range: 1 to 36 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A.

name

String

Definition: Workspace name.

Constraints: N/A.

Range: 4 to 32 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A.

description

String

Definition: Description entered by a user.

Constraints: N/A.

Range: 0 to 255 characters.

Default Value: N/A.

create_time

String

Definition: Creation time.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

create_domain_name

String

Definition: Account name.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

create_user_name

String

Definition: Username.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

metastore_id

String

Definition: Instance ID of LakeFormation, that is, MetaStore ID.

Constraints: N/A.

Range: 32 to 36 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: N/A.

access_url

String

Definition: Resource access address.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

enterprise_project_id

String

Definition: Enterprise project ID. For how to obtain an enterprise project ID, see [Obtaining an Enterprise Project ID] (dataartsfabric_03_0027.xml).

Constraints: This parameter can be set only when an enterprise project is connected.

Range: 1 to 64 characters. Only letters, digits, and hyphens (-) are allowed.

Default Value: 0, meaning the default ID is used.

tags

Array of ResourceTag objects

Definition: Resource tag of a workspace.

Constraints: N/A.

Table 5 ResourceTag

Parameter

Type

Description

key

String

Definition: Resource tag key. For details about how to obtain a tag key, see "API Description" > "Resource Tags" > "Querying Tag Keys" in Tag Management Service API Reference.

Constraints: N/A.

Range: 1 to 128 characters. Only letters, spaces, tabs, digits, underscores (_), periods (.), colons (:), backslashes (), equal signs (=), plus signs (+), minus signs (-), and at signs (@) are allowed.

Default Value: N/A.

value

String

Definition: Resource tag value.

Constraints: N/A.

Range: 0 to 255 characters. Only letters, spaces, tabs, digits, underscores (_), periods (.), colons (:), backslashes (), equal signs (=), plus signs (+), minus signs (-), and at signs (@) are allowed.

Default Value: N/A.

Status code: 400

Table 6 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: 8 to 36 characters.

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: 2 to 512 characters.

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: 0 to 4,096 characters.

Default Value: N/A.

Status code: 401

Table 7 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: 8 to 36 characters.

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: 2 to 512 characters.

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: 0 to 4,096 characters.

Default Value: N/A.

Status code: 404

Table 8 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: 8 to 36 characters.

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: 2 to 512 characters.

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: 0 to 4,096 characters.

Default Value: N/A.

Status code: 408

Table 9 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: 8 to 36 characters.

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: 2 to 512 characters.

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: 0 to 4,096 characters.

Default Value: N/A.

Status code: 500

Table 10 Response body parameters

Parameter

Type

Description

error_code

String

Definition: Error code.

Constraints: N/A.

Range: 8 to 36 characters.

Default Value: N/A.

error_msg

String

Definition: Error message.

Constraints: N/A.

Range: 2 to 512 characters.

Default Value: N/A.

solution_msg

String

Definition: Solution description.

Constraints: N/A.

Range: 0 to 4,096 characters.

Default Value: N/A.

Example Requests

Create a workspace. The name is fabric, the description is fabric-description, the corresponding MetaStore ID is xxxxxx, the enterprise project ID is 01049549-82cd-4b2b-9733-ddb94350c125, the tags are key1 with value value1, and key2 with value value2.

POST https://{endpoint}/v1/workspaces

{
  "name" : "fabric",
  "description" : "fabric-description",
  "metastore_id" : "xxxxxx",
  "enterprise_project_id" : "01049549-82cd-4b2b-9733-ddb94350c125",
  "tags" : [ {
    "key" : "key1",
    "value" : "value1"
  }, {
    "key" : "key2",
    "value" : "value2"
  } ]
}

Example Responses

Status code: 200

A workspace list is created.

{
  "id" : "90a827a1-ca72-4be8-943b-774f94xxxxxx",
  "name" : "workspace1",
  "description" : "workspace1-description",
  "create_time" : "2025-01-10T03:37:12.000+00:00",
  "create_domain_name" : "create_domain_name_001",
  "create_user_name" : "create_user_name_001",
  "metastore_id" : "2180518f-42b8-4947-b20b-adfc539xxxxx",
  "access_url" : "https://:test.fabric.com/",
  "enterprise_project_id" : 0
}

Status code: 400

BadRequest

{
  "error_code" : "common.01000001",
  "error_msg" : "failed to read http request, please check your input, code: 400, reason: Type mismatch., cause: TypeMismatchException"
}

Status code: 401

Unauthorized

{
  "error_code" : "APIG.1002",
  "error_msg" : "Incorrect token or token resolution failed"
}

Status code: 403

Forbidden

{
  "error" : {
    "code" : "403",
    "message" : "X-Auth-Token is invalid in the request",
    "title" : "Forbidden"
  },
  "error_code" : 403,
  "error_msg" : "X-Auth-Token is invalid in the request",
  "title" : "Forbidden"
}

Status code: 404

NotFound

{
  "error_code" : "common.01000001",
  "error_msg" : "response status exception, code: 404"
}

Status code: 408

Request Time-out

{
  "error_code" : "common.00000408",
  "error_msg" : "timeout exception occurred"
}

Status code: 500

InternalServerError

{
  "error_code" : "common.00000500",
  "error_msg" : "internal error"
}

Status Codes

Status Code

Description

200

A workspace list is created.

400

BadRequest

401

Unauthorized

403

Forbidden

404

NotFound

408

Request Time-out

500

InternalServerError

Error Codes

See Error Codes.