Help Center/ ModelArts/ API Reference/ Workspace Management/ Modifying a Workspace
Updated on 2026-01-30 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Modifying a Workspace

Function

This API is used to update the configuration information of a specified workspace.

This API is used when you need to change the name, description, or other configuration information of a workspace. Before using this API, ensure that the workspace exists and you have the permission to modify the workspace. After the modification is complete, the API returns the updated workspace details, including the workspace name, description, and update time. If the workspace does not exist or you do not have the operation permission, the API will return an error message.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, the following identity policy-based permissions are required.

    Action

    Access Level

    Resource Type (*: required)

    Condition Key

    Alias

    Dependencies

    modelarts:workspace:update

    Write

    workspace *

    -

    -

    -

URI

PUT /v1/{project_id}/workspaces/{workspace_id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition: User project ID. For details, see Obtaining a Project ID and Name.

Constraints: N/A

Range: N/A

Default Value: N/A

workspace_id

Yes

String

Definition: Workspace ID. If no workspaces are available, the default value is 0. If a workspace is created and used, use the actual value.

Constraints: N/A

Range: N/A

Default Value: N/A

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Definition: User token. It can be obtained by calling the IAM API. The token is the value of X-Subject-Token in the response header.

Constraints: N/A

Range: N/A

Default Value: N/A
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

grants

No

Array of grants objects

Definition: Authorization user list.

Constraints: This parameter is valid only when auth_type is set to INTERNAL. The value contains a maximum of 500 characters.

auth_type

No

String

Definition: Authorization type.

Constraints: N/A

Range:

  • PUBLIC: accessible to tenants

  • PRIVATE: accessible only to the creator and tenant accounts

  • INTERNAL: accessible to the creator, tenant accounts, and specified IAM users. This parameter must be used with grants.

Default Value: PUBLIC

name

No

String

Definition: Workspace name.Constraints: Enter 4 to 64 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. default is the name of the default workspace reserved by the system. You are not allowed to create a workspace named default.Range: N/ADefault Value: N/A

description

No

String

Definition: Workspace description.

Constraints: The value can contain at most 256 characters.

Range: N/A

Default Value: This parameter is left empty by default.
Table 4 grants

Parameter

Mandatory

Type

Description

user_id

No

String

Definition: User ID.

Constraints: If user_type is set to IAM, either user_name or user_id must be specified. user_id is recommended. This parameter is mandatory for agencies. This parameter is ignored for federated users. The response is automatically generated.

Range: N/A.

Default Value: N/A.

user_name

No

String

Definition: Username.

Constraints: If user_type is set to IAM, either user_id or user_name must be specified. user_id is recommended. This parameter is mandatory for agencies and federated users.

Range: N/A.

Default Value: N/A.

user_type

No

String

Definition

Authorized user type.

Constraints

This parameter is mandatory for federated users or agency users.

Range

IAM: IAM user

FEDERATE: federated user

AGENCY: agency user

Default Value

IAM

Response Parameters

Status code: 200

Table 5 Response body parameters

Parameter

Type

Description

workspace_id

String

Definition: Workspace ID.

Range: N/A

Example Requests

PUT https://{endpoint}/v1/{project_id}/workspaces/ccd05d1a553b4e188ea878e7dcb85e47

{
  "name" : "my_workspace",
  "description" : "It is my workspace",
  "auth_type" : "INTERNAL",
  "grants" : [ {
    "user_name" : "my_iam_user"
  } ]
}

Example Responses

Status code: 200

Response parameter indicating that a workspace is modified

{
  "workspace_id" : "***05d1a553b4e188ea878e7dcb85***"
}

Status Codes

Status Code

Description

200

Response parameter indicating that a workspace is modified

Error Codes

See Error Codes.

Parent topic: Workspace Management