Updating a Notebook Instance

Updated on 2025-08-20 GMT+08:00

View PDF

Function

This API is used to modify the instance configurations, including its name, description, specifications, and image.

This API applies to the following scenario: When you need to modify the configuration of a notebook instance to adapt to new requirements, you can use this API to update the instance details. Before using this API, ensure that you have logged in to the system and have the permission to perform operations on the target notebook instance. In addition, the notebook instance must have been stopped. After this API is called, the system updates the configuration of the specified notebook instance. If you do not have the permission to perform operations on the specified notebook instance or the notebook instance has not been stopped, the API will return an error message. If the specified notebook instance is not found or the modification to the parameters is invalid, the API will return an error message.

Constraints

None

Debugging

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

URI

PUT /v1/{project_id}/notebooks/{id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
id	Yes	String	Definition: Notebook instance ID. The ID is in the format of a Universally Unique Identifier (UUID). For details about how to obtain the ID, see Querying Notebook Instances. Constraints: N/A Range: N/A Default Value: N/A
project_id	Yes	String	Definition: Project ID. For details, see Obtaining a Project ID and Name. Constraints: N/A Range: N/A Default Value: N/A

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
description	No	String	Definition: Instance description can be updated. Constraints: N/A Range: The value can contain up to 512 characters and cannot contain special characters (&<>"'/). Default Value: N/A
endpoints	No	Array of EndpointsReq objects	Definition: Only local IDE (such as PyCharm and VS Code) or SSH client can be used to access a notebook instance. Constraints: Configurations required for remotely accessing a notebook instance through SSH only on the local IDE (such as PyCharm and VS Code) or SSH client.
flavor	No	String	Definition: The machine specifications of the notebook instance can be changed. Specifications that can be changed. You can call the API in Querying Flavors Available for a Notebook Instance to obtain them. Constraints: N/A Range: N/A Default Value: N/A
image_id	No	String	Definition: Image ID can be updated. For details, see Querying Supported Images. Constraints: N/A Range: Valid image IDs obtained by calling APIs in Querying Supported Images. Default Value: N/A
name	No	String	Definition: Instance name can be updated. Constraints: N/A Range: The value can contain a maximum of 128 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed. The name can be repeated. Default Value: N/A
storage_new_size	No	Integer	Definition: EVS instance capacity that can be expanded dynamically, in GB. Only scale-out is supported. Constraints: N/A Range: The capacity can be expanded to at most 4,096 GB. Default Value: N/A
hooks	No	CustomHooks object	Definition: The instance startup script can be updated. Constraints: N/A

**Table 3** EndpointsReq
Parameter	Mandatory	Type	Description
allowed_access_ips	No	Array of strings	Definition: Public IP addresses that can remotely access the notebook instance. A maximum of five public IP addresses are supported. Constraints: N/A
service	No	String	Definition: Supported services. Constraints: N/A Range: NOTEBOOK: You can access notebook instances using HTTPS. SSH: You can remotely access notebook instances through SSH. Default Value: N/A
key_pair_names	No	Array of strings	Definition: Name of the SSH key pair, which can be created and viewed on the Key Pair page of the Elastic Cloud Server (ECS) console. Constraints: N/A

**Table 4** CustomHooks
Parameter	Mandatory	Type	Description
container_hooks	No	ContainerHooks object	Definition: Container hook configuration. Constraints: N/A

**Table 5** ContainerHooks
Parameter	Mandatory	Type	Description
post_start	No	Config object	Definition: Script configuration after the service is started. Constraints: N/A
pre_start	No	Config object	Definition: Script configuration before the service is started. Constraints: N/A

**Table 6** Config
Parameter	Mandatory	Type	Description
script	No	String	Definition: Custom script (Base64 encoding) or absolute path of a script. Constraints: N/A Range: N/A Default Value: N/A
type	No	String	Definition: Script type. Constraints: N/A Range: COMMAND: The script content (Base64-encoded) must be specified. SCRIPT (default): The script path must be specified. Default Value: N/A

Response Parameters

Status code: 200

**Table 7** Response body parameters
Parameter	Type	Description
action_progress	Array of JobProgress objects	Definition: Initialization progress of the instance.
description	String	Definition: Instance description. Range: N/A
endpoints	Array of EndpointsRes objects	Definition: Local IDE (such as PyCharm and VS Code) or SSH client for remotely accessing a notebook instance through SSH.
fail_reason	String	Definition: Instance failure cause. Range: N/A
flavor	String	Definition: Instance flavor. Range: N/A
id	String	Definition: Instance ID. Range: N/A
image	Image object	Definition: Instance image information.
lease	Lease object	Definition: Countdown to auto stop of an instance.
name	String	Definition: Instance name. Range: N/A
pool	Pool object	Definition: Basic information about the dedicated pool, which is returned by the instance created in the dedicated pool.
status	String	Definition: Instance status. Range: INIT: The instance is being initialized. CREATING: The instance is being created. STARTING: The instance is being started. STOPPING: The instance is being stopped. DELETING: The instance is being deleted. RUNNING: The instance is running. STOPPED: The instance has been stopped. SNAPSHOTTING: The image of the instance is being saved. CREATE_FAILED: Creating the instance failed. START_FAILED: Starting the instance failed. DELETE_FAILED: Deleting the instance failed. ERROR: An error occurred. DELETED: The instance has been deleted. FROZEN: The instance is frozen.
token	String	Description: Token used for notebook authentication. Range: N/A
url	String	Definition: URL for accessing the instance. Range: N/A
volume	VolumeRes object	Definition: Instance storage information.
workspace_id	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. Range: N/A
feature	String	Definition: Instance type. Range: DEFAULT: free CodeLab instance. Each user can create only one. NOTEBOOK: billed instance.
billing_items	Array of strings	Definition: Billing resource type. Range: STORAGE: Storage resource billing COMPUTE: Computing resources billing ALL: All billing types
user	user object	Description: Account information.

**Table 8** JobProgress
Parameter	Type	Description
notebook_id	String	Definition: Instance ID. Range: N/A
status	String	Definition: Job status in a specified step. Range: WAITING: The job is awaiting. PROCESSING: The job is being processed. FAILED: The job failed. COMPLETED: The job is complete.
step	Integer	Definition: Job step. Range: 1: Prepare storage. 2: Prepare compute resources. 3: Configure the network. 4: Initialize the instance.
step_description	String	Definition: Job description in a specified step. Range: N/A

**Table 9** EndpointsRes
Parameter	Type	Description
allowed_access_ips	Array of strings	Definition: Whitelisted public IP addresses that are allowed to access notebook instances through SSH. By default, all public IP addresses can access the notebook instances. If IP addresses are specified, only the clients with the specified IP addresses can access the notebook instances.
dev_service	String	Definition: Method for accessing the notebook instance. Range: NOTEBOOK: You can access notebook instances using HTTPS. SSH: You can remotely access notebook instances through SSH.
ssh_keys	Array of strings	Definition: List of SSH key pairs. You can set multiple key pairs to access an SSH instance at the same time.
service	String	Definition: Method for accessing the notebook instance. Range: NOTEBOOK: You can access notebook instances using HTTPS. SSH: You can remotely access notebook instances through SSH.
uri	String	Definition: Private IP address of the instance. Range: N/A

**Table 10** Image
Parameter	Type	Description
arch	String	Definition: Processor architecture supported by the image. Range: X86_64: x86 architecture AARCH64: Arm architecture
create_at	Long	Definition: UTC time when the image is created, accurate to millisecond. Range: N/A
description	String	Definition: Image description. Range: Up to 512 characters
dev_services	Array of strings	Definition: Services supported by the image. Range: NOTEBOOK: You can access a notebook instance using HTTPS. SSH: You can remotely access a notebook instance from a local IDE through SSH.
id	String	Definition: ID of the image used for creating notebook instances. The ID is in Universally Unique Identifier (UUID) format. For details, see Querying Supported Images. Range: N/A
name	String	Definition: Image name. Range: The name can contain a maximum of 512 characters. Lowercase letters, digits, hyphens (-), underscores (_), and periods (.) are allowed.
namespace	String	Definition: Organization to which the image belongs. You can create and view an organization on the Organization Management page of the SWR console. Range: N/A
origin	String	Definition: Image source. Range: CUSTOMIZE: custom image IMAGE_SAVE: image saved by a notebook instance
resource_categories	Array of strings	Definition: Flavors supported by the image. Range: CPU GPU ASCEND
service_type	String	Definition: Supported image types. Range: COMMON: common image INFERENCE: image used for inference TRAIN: image used for training DEV: image used for development and debugging UNKNOWN: image whose supported services are not specified
size	Long	Definition: Image size, in KB. Range: N/A
status	String	Definition: Image status. Range: INIT: The image is being initialized. CREATING: The image is being saved. In this case, the notebook instance is unavailable. CREATE_FAILED: Saving the image failed. ERROR: An error occurs. DELETED: The image has been deleted. ACTIVE: The image has been saved, which you can view on the SWR console and use to create notebook instances.
status_message	String	Definition: Build information during image saving. Range: N/A
support_res_categories	Array of strings	Definition: Flavors supported by the image. Range: CPU GPU ASCEND
swr_path	String	Definition: SWR image path. Range: N/A
tag	String	Definition: Image tag. Range: N/A
type	String	Definition: Image type. Range: BUILD_IN: built-in system image DEDICATED: image you have saved
update_at	Long	Definition: Time (UTC) when the image was last updated, accurate to millisecond. Range: N/A
visibility	String	Definition: Image visibility. Range: PRIVATE: private image PUBLIC: All users can perform read-only operations based on image_id.
workspace_id	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. Range: N/A
flavor_type	String	Definition: Resource type of the image. Range: ASCEND_SNT9 ASCEND_SNT9B ASCEND_SNT3

**Table 11** Lease
Parameter	Type	Description
create_at	Long	Definition: UTC time when the instance is created, accurate to millisecond. Range: N/A
duration	Long	Definition: Instance runtime, which is calculated based on the instance creation time. If the instance creation time plus the runtime is greater than the current time, the system automatically stops the instance. Range: N/A
enable	Boolean	Definition: Specifies whether to enable auto stop. Range: Boolean true: Auto stop is enabled. false: Auto stop is disabled.
type	String	Definition: Auto stop type. Range: TIMING: auto stop IDLE: stop when idle
update_at	Long	Definition: Time (UTC) when the instance is last updated (excluding liveness check), accurate to millisecond. Range: N/A

**Table 12** Pool
Parameter	Type	Description
id	String	Definition: Dedicated resource pool ID. Range: N/A
name	String	Definition: Dedicated resource pool name. Range: N/A

**Table 13** VolumeRes
Parameter	Type	Description
capacity	Integer	Definition: Storage capacity. Range: The default value is 5 GB for EVS and 50 GB for EFS. The maximum value is 4,096 GB.
category	String	Definition: Supported storage type. For details about the differences between the storage types, see Selecting Storage in DevEnviron. Range: SFS EVS OBS OBSFS: parallel file system EFS: SFS Turbo
mount_path	String	Definition: Directory of the notebook instance to which the storage is mounted. Currently, the directory is /home/ma-user/work/. Range: N/A
ownership	String	Definition: Resource owner. Range: MANAGED: Resources are managed by the service. DEDICATED: Resources are managed by the user account. This mode is supported only when the instance category is EFS.
status	String	Definition: EVS disk capacity expansion status, which is RESIZING during capacity expansion and does not affect the instance. Range: N/A

**Table 14** user
Parameter	Type	Description
domain	domain object	Description: Domain information of the account.
id	String	Definition: IAM user ID. For details, see Obtaining a Username and ID. Range: N/A
name	String	Definition: IAM username. Range: N/A

**Table 15** domain
Parameter	Type	Description
id	String	Definition: Account ID. Range: N/A
name	String	Definition: Account name. Range: N/A

Status code: 201

Created

Example Requests

{
  "description" : "update"
}

Example Responses

Status code: 200

{
  "description" : "test",
  "flavor" : "modelarts.vm.cpu.8u",
  "name" : "notebook-1111",
  "endpoints" : [ {
    "allowed_access_ips" : [ "1.1.1.1" ]
  } ]
}