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

Modifying an Endpoint

Function

This API is used to update an endpoint. You can call this API to update the details of an endpoint by providing inputs such as the name, description, resource configuration, and image package configuration. The updated endpoint information will then be returned. However, note that the log_config of a Ray service remains unaffected and cannot be updated through this operation. This is an asynchronous API. It is used in conjunction with the ShowEndpoint API to query information about an endpoint, with no specific scenarios involved.

URI

PUT /v1/workspaces/{workspace_id}/endpoints/{endpoint_id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

workspace_id

Yes

String

Definition: Workspace ID. For how to obtain a workspace ID, see [Obtaining a Workspace ID] (dataartsfabric_03_0022.xml).

Constraints: N/A.

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

Default Value: N/A.

endpoint_id

Yes

String

Definition: Endpoint ID. For how to obtain an endpoint ID, see [Obtaining an Endpoint ID] (dataartsfabric_03_0023.xml).

Constraints: N/A.

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

Default Value: N/A.

Request Parameters

Table 2 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 3 Request body parameters

Parameter

Mandatory

Type

Description

name

No

String

Definition: Endpoint name.

Constraints: N/A.

Range: 1 to 128 characters. Only letters, digits, hyphens (-), underscores (_), periods (.), and spaces are allowed.

Default Value: N/A.

description

No

String

Definition: Description.

Constraints: N/A.

Range: [0, 1024].

Default Value: N/A.

reserved_resource

No

ReservedResource object

Definition: General reserved resources.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

ray_resource

No

RayResourceInput object

Definition: Resource configuration for creating a Ray cluster.

Constraints: N/A.

cap

No

CapRef object

Definition: Image package information.

Constraints: N/A.

config

No

EndpointConfig object

Definition: Endpoint configuration.

Constraints: N/A.

public_access

No

Boolean

Definition: Whether to enable public network access.

Constraints: N/A.

Range: true (enabled) or false (disabled).

Default Value: N/A.

Table 4 ReservedResource

Parameter

Mandatory

Type

Description

apu

No

ResourceDef object

Definition: Resource definition.

Constraints: N/A.

dpu

No

SqlResourceDef object

Definition: SQL resource definition.

Constraints: N/A.

mu

No

ResourceDemand object

Definition: Resource requirement configuration.

Constraints: N/A.

Table 5 ResourceDef

Parameter

Mandatory

Type

Description

spec_code

Yes

String

Definition: Endpoint status.

Constraints: Resource specification code, which is queried using the ListSpecs API.

Range: N/A.

Default Value: N/A.

warm_up_num

Yes

Integer

Definition: Number of resources to be warmed up.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

max_num

No

Integer

Definition: Maximum number of resources. If left blank, it defaults to the preheating resource amount, meaning elastic resources are not used.

Constraints: N/A.

Range: [1, 1000].

Default Value: N/A.

Table 6 SqlResourceDef

Parameter

Mandatory

Type

Description

spec_code

Yes

String

Definition: Endpoint status.

Constraints: Resource specification code, which is queried using the ListSpecs API.

Range: N/A.

Default Value: N/A.

warm_up_num

Yes

Integer

Definition: Number of resources to be warmed up.

Constraints: N/A.

Range: [1, 5000].

Default Value: N/A.

max_num

No

Integer

Definition: Maximum number of resources. If left unset, it defaults to the preheating resource amount, meaning elastic resources are not used.

Constraints: N/A.

Range: [1, 5000].

Default Value: N/A.

use_public_resource

No

Boolean

Definition: Whether to use public resources.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

Table 7 RayResourceInput

Parameter

Mandatory

Type

Description

head_node_resource

Yes

HeadNodeResourceDemand object

Definition: headNode resource requirement configuration.

Constraints: N/A.

work_node_resources

Yes

Array of WorkNodeResourceDemand objects

Definition: Resource configuration of worker nodes.

Constraints: N/A.

Range: [1, 10].

Default Value: N/A.

Table 8 HeadNodeResourceDemand

Parameter

Mandatory

Type

Description

spec_code

Yes

String

Definition: Resource specifications.

Constraints: N/A.

Range: The value must be queried from the specifications list.

Default Value: N/A.

Table 9 WorkNodeResourceDemand

Parameter

Mandatory

Type

Description

name

Yes

String

Definition: Resource configuration name.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

resource

Yes

ResourceDemand object

Definition: Resource requirement configuration.

Constraints: N/A.

Table 10 ResourceDemand

Parameter

Mandatory

Type

Description

spec_code

Yes

String

Definition: Resource specifications.

Constraints: N/A.

Range: The value must be queried from the specifications list.

Default Value: N/A.

min

Yes

Integer

Definition: Minimum number.

Constraints: N/A.

Range: The minimum value is 0.

Default Value: N/A.

max

Yes

Integer

Definition: Maximum number.

Constraints: N/A.

Range: The minimum value is 1.

Default Value: N/A.

Table 11 CapRef

Parameter

Mandatory

Type

Description

cap_id

No

String

Definition: Image package ID.

Constraints: N/A.

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

Default Value: N/A.

version_id

No

String

Definition: Image package version ID.

Constraints: N/A.

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

Default Value: N/A.

Table 12 EndpointConfig

Parameter

Mandatory

Type

Description

ray_service_config

No

RayServiceConfig object

Definition: Configuration of a Ray service endpoint.

Constraints: N/A.

Table 13 RayServiceConfig

Parameter

Mandatory

Type

Description

ray_serve_config

Yes

RayServeConfig object

Definition: Ray Serve configuration.

Constraints: N/A.

ray_cluster_config

Yes

RayClusterConfig object

Definition: Ray cluster configuration.

Constraints: N/A.

log_config

No

RayServiceLogConfig object

Definition: Log configuration of a Ray service.

Constraints: N/A.

data_infos

No

Array of DataBriefInfo objects

Definition: Data information.

Constraints: N/A.

Range: [0, 1].

Default Value: N/A.

Table 14 RayServeConfig

Parameter

Mandatory

Type

Description

applications

No

Array of ServeApplication objects

Definition: Application.

Constraints: N/A.

Range: [0, 5].

Default Value: N/A.

Table 15 ServeApplication

Parameter

Mandatory

Type

Description

name

Yes

String

Definition: Application name.

Constraints: N/A.

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

Default Value: N/A.

import_path

Yes

String

Definition: Input path.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

deployments

Yes

Array of Deployment objects

Definition: Deployment list.

Constraints: N/A.

Range: [1, 5].

Default Value: N/A.

runtime_env

Yes

ServeRuntimeEnv object

Definition: Runtime environment configuration of Serve.

Constraints: N/A.

Range: working_dir: working directory where the code will run. The value must be a remote URI, such as an S3 or a local path; env_vars: environment variables to be set.

Default Value: N/A.

route_prefix

No

String

Definition: Route prefix.

Constraints: The value must be unique in Ray Serve and cannot be the same as the prefixes of other applications.

Range: N/A.

Default Value: N/A.

Table 16 Deployment

Parameter

Mandatory

Type

Description

name

No

String

Description: Name of a deployment.

Constraints: N/A.

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

Default Value: N/A.

ray_actor_options

No

RayActorOptions object

Definition: Ray actor configuration.

Constraints: N/A.

autoscaling_config

No

AutoscalingConfig object

Definition: Auto scaling configuration.

Constraints: N/A.

num_replicas

No

Integer

Definition: Number of replicas.

Constraints: N/A.

Range: [0, 1000].

Default Value: N/A.

user_config

No

Object

Definition: User-defined configuration.

Constraints: N/A.

max_replicas_per_node

No

Integer

Definition: Maximum number of replicas allowed per node.

Constraints: N/A.

Range: [1, 100].

Default Value: 1.

max_ongoing_requests

No

Integer

Definition: Maximum number of concurrent requests that each replica can accept.

Constraints: N/A.

Range: [1, 100000].

Default Value: N/A.

max_queued_requests

No

Integer

Definition: Maximum number of queued requests that a deployment can accept. –1 indicates no limit.

Constraints: N/A.

Range: [-1, 100000].

Default Value: N/A.

Table 17 RayActorOptions

Parameter

Mandatory

Type

Description

num_cpus

No

Double

Definition: CPU size.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

memory

No

Double

Definition: Memory size.

Constraints: N/A.

Range: N/A.

Default Value: N/A.

resources

No

String

Definition: Resource configuration.

Constraints: N/A.

Range: [0, 1024].

Default Value: N/A.

Table 18 AutoscalingConfig

Parameter

Mandatory

Type

Description

target_ongoing_requests

No

Integer

Definition: Average number of requests that each replica can provide per unit time.

Constraints: N/A.

Range: [1, 1000].

Default Value: N/A.

min_replicas

No

Integer

Definition: Minimum number of replicas.

Constraints: N/A.

Range: [0, 1000].

Default Value: N/A.

max_replicas

No

Integer

Definition: Maximum number of replicas.

Constraints: N/A.

Range: [0, 1000].

Default Value: N/A.

initial_replicas

No

Integer

Definition: Number of initial replicas.

Constraints: N/A.

Range: [0, 1000].

Default Value: N/A.

upscale_delay_s

No

Integer

Definition: Waiting time before scale-up.

Constraints: N/A.

Range: [0, 86400].

Default Value: N/A.

downscale_delay_s

No

Integer

Definition: Waiting time before scale-down.

Constraints: N/A.

Range: [0, 86400].

Default Value: N/A.

Table 19 ServeRuntimeEnv

Parameter

Mandatory

Type

Description

working_dir

No

String

Definition: Working directory where the code will run.

Constraints: The value must be a remote URI, for example, an S3 or a local path.

Range: N/A.

Default Value: N/A.

env_vars

No

Map<String,String>

Definition: Environment variables to be set.

Constraints: N/A.

Table 20 RayClusterConfig

Parameter

Mandatory

Type

Description

enable_custom

No

Boolean

Definition: Whether to enable resource customization.

Constraints: N/A.

Range: true (enabled) or false (disabled).

Default Value: false.

head_group_spec

Yes

HeadGroupSpecV2 object

Definition: Head group configuration.

Constraints: N/A.

worker_group_specs

Yes

Array of WorkerGroupSpecV2 objects

Definition: Worker group configuration.

Constraints: [1, 1000].

Table 21 HeadGroupSpecV2

Parameter

Mandatory

Type

Description

limits

No

ResourceSpec object

Definition: Resource configuration.

Constraints: N/A.

requests

No

ResourceSpec object

Definition: Resource configuration.

Constraints: N/A.

Table 22 WorkerGroupSpecV2

Parameter

Mandatory

Type

Description

name

No

String

Definition: Name.

Constraints: N/A.

Range: 0 to 128 characters. Only letters, digits, hyphens (-), and underscores (_) are allowed.

Default Value: N/A.

min_replicas

No

Integer

Definition: Minimum number of replicas.

Constraints: N/A.

Range: [0, 10000].

Default Value: N/A.

max_replicas

No

Integer

Definition: Maximum number of replicas.

Constraints: N/A.

Range: [1, 10000].

Default Value: N/A.

limits

No

ResourceSpec object

Definition: Resource limit.

Constraints: N/A.

requests

No

ResourceSpec object

Definition: Minimum number of resources.

Constraints: N/A.

Table 23 ResourceSpec

Parameter

Mandatory

Type

Description

spec_code

No

String

Definition: Resource specifications.

Constraints: N/A.

Range: The value must be queried from the specifications list.

Default Value: N/A.

cpu_resource

No

Integer

Definition: Number of CPU cores.

Constraints: N/A.

Range: [0, 192].

Default Value: null.

memory_resource

No

Integer

Definition: Memory size.

Constraints: N/A.

Range: [0, 1536].

Default Value: null.

npu_resource

No

Integer

Definition: Number of Huawei Cloud AI processing units (PUs).

Constraints: N/A.

Range: [0, 8].

Default Value: null.

Table 24 RayServiceLogConfig

Parameter

Mandatory

Type

Description

lts

No

RayServiceLogLtsConfig object

Definition: Log configuration of a Ray service.

Constraints: N/A.

Table 25 RayServiceLogLtsConfig

Parameter

Mandatory

Type

Description

enabled

No

Boolean

Definition: Whether to enable the function of dumping Ray service logs to LTS.

Constraints: N/A.

Range: true or false.

Default Value: false.

log_group_id

No

String

Definition: ID of an LTS log group where Ray service logs are dumped.

Constraints: The ID must correspond to an existing LTS log group.

Range: N/A.

Default Value: N/A.

log_stream_id

No

String

Definition: ID of an LTS log stream where Ray service logs are dumped.

Constraints: The ID must correspond to an existing LTS log stream.

Range: N/A.

Default value: N/A.

Table 26 DataBriefInfo

Parameter

Mandatory

Type

Description

input_path

No

String

Definition: Address.

Constraints: N/A.

Range: [4, 1024].

Default Value: N/A.

Response Parameters

Status code: 202

Endpoint details are queried.

Status code: 400

Table 27 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 28 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 29 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 30 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

Update an endpoint. Specific update information is shown in the following example.

PUT https://{endpoint}/v1/workspaces/{workspace_id}/endpoints/{endpoint_id}

{
  "name" : "endpoint1",
  "description" : "description",
  "reserved_resource" : {
    "apu" : {
      "spec_code" : "dpu.d1x",
      "warm_up_num" : 1,
      "max_num" : 100
    },
    "dpu" : {
      "spec_code" : "dpu.d1x",
      "warm_up_num" : 1,
      "max_num" : 100,
      "use_public_resource" : false
    },
    "mu" : {
      "spec_code" : "string",
      "min" : 0,
      "max" : 1
    }
  },
  "ray_resource" : {
    "head_node_resource" : {
      "spec_code" : "string"
    },
    "work_node_resources" : [ {
      "name" : "cpuGroup1",
      "resource" : {
        "spec_code" : "string",
        "min" : 0,
        "max" : 1
      }
    } ]
  },
  "cap" : {
    "cap_id" : "0b5633ba2b904511ad514346f4d23d4b",
    "version_id" : "0b5633ba2b904511ad514346f4d23d4b"
  },
  "config" : {
    "ray_service_config" : {
      "ray_serve_config" : {
        "applications" : [ {
          "name" : "string",
          "import_path" : "string",
          "deployments" : [ {
            "name" : "string",
            "ray_actor_options" : {
              "num_cpus" : 0,
              "memory" : 0,
              "resources" : "string"
            },
            "autoscaling_config" : {
              "target_ongoing_requests" : 1000,
              "max_ongoing_requests" : 1000,
              "min_replicas" : 1000,
              "max_replicas" : 1000,
              "initial_replicas" : 1000,
              "upscale_delay_s" : 86400,
              "downscale_delay_s" : 86400
            },
            "num_replicas" : 1000,
            "user_config" : { },
            "max_replicas_per_node" : 1
          } ],
          "runtime_env" : {
            "working_dir" : "string",
            "env_vars" : {
              "additionalProp1" : "string",
              "additionalProp2" : "string",
              "additionalProp3" : "string"
            }
          },
          "route_prefix" : "string"
        } ]
      },
      "ray_cluster_config" : {
        "head_group_spec" : {
          "limits" : {
            "spec_code" : "string"
          },
          "requests" : {
            "spec_code" : "string"
          }
        },
        "worker_group_specs" : [ {
          "name" : "string",
          "min_replicas" : 10000,
          "max_replicas" : 10000,
          "limits" : {
            "spec_code" : "string"
          },
          "requests" : {
            "spec_code" : "string"
          }
        } ]
      },
      "data_infos" : [ {
        "input_path" : "OBS://bucket/dir/"
      } ]
    }
  }
}

Example Responses

Status code: 202

Endpoint details are queried.

{
  "visibility" : "PRIVATE",
  "id" : "0b5633ba2b904511ad514346f4d23d4b",
  "name" : "endpoint1",
  "type" : "job",
  "status" : "CREATING",
  "description" : "description",
  "create_time" : "2023-05-30T12:24:30.401Z",
  "update_time" : "2023-05-30T12:24:30.401Z",
  "owner" : {
    "domain_name" : "string",
    "domain_id" : "0b5633ba2b904511ad514346f4d23d4b",
    "user_name" : "string",
    "user_id" : "0b5633ba2b904511ad514346f4d23d4b"
  },
  "cap" : {
    "cap_id" : "0b5633ba2b904511ad514346f4d23d4b",
    "version_id" : "0b5633ba2b904511ad514346f4d23d4b"
  },
  "reserved_resource" : {
    "apu" : {
      "spec_code" : "dpu.d1x",
      "warm_up_num" : 1,
      "max_num" : 100
    },
    "dpu" : {
      "spec_code" : "dpu.d1x",
      "warm_up_num" : 1,
      "max_num" : 100,
      "use_public_resource" : false
    },
    "mu" : {
      "spec_code" : "string",
      "min" : 0,
      "max" : 1
    }
  },
  "ray_resource" : {
    "head_group_spec" : {
      "spec_code" : "string"
    },
    "worker_group_spec" : [ {
      "name" : "string",
      "spec_code" : "string",
      "min_replicas" : 10000,
      "max_replicas" : 10000
    } ]
  },
  "caches" : [ {
    "mnt_path" : "string",
    "cache_ins_id" : "string"
  } ],
  "error_code" : "string",
  "error_msg" : "string",
  "urls" : [ {
    "name" : "string",
    "address" : "string",
    "type" : "PRIVATE",
    "token" : "string"
  } ],
  "business_engine_instance_ids" : [ "string" ],
  "tokens_quota" : {
    "total" : 0,
    "used" : 0,
    "expire_time" : "2025-01-17T07:30:35.677Z"
  },
  "runtime_env_type" : "RELEASE",
  "config" : {
    "ray_service_config" : {
      "ray_serve_config" : {
        "applications" : [ {
          "name" : "string",
          "import_path" : "string",
          "deployments" : [ {
            "name" : "string",
            "ray_actor_options" : {
              "num_cpus" : 0,
              "memory" : 0,
              "resources" : "string"
            },
            "autoscaling_config" : {
              "target_ongoing_requests" : 1000,
              "max_ongoing_requests" : 1000,
              "min_replicas" : 1000,
              "max_replicas" : 1000,
              "initial_replicas" : 1000,
              "upscale_delay_s" : 86400,
              "downscale_delay_s" : 86400
            },
            "num_replicas" : 1000,
            "user_config" : { },
            "max_replicas_per_node" : ""
          } ],
          "runtime_env" : {
            "working_dir" : "string",
            "env_vars" : {
              "additionalProp1" : "string",
              "additionalProp2" : "string",
              "additionalProp3" : "string"
            }
          },
          "route_prefix" : "string"
        } ]
      },
      "ray_cluster_config" : {
        "head_group_spec" : {
          "limits" : {
            "spec_code" : "string"
          },
          "requests" : {
            "spec_code" : "string"
          }
        },
        "worker_group_specs" : [ {
          "name" : "string",
          "min_replicas" : 10000,
          "max_replicas" : 10000,
          "limits" : {
            "spec_code" : "string"
          },
          "requests" : {
            "spec_code" : "string"
          }
        } ]
      },
      "data_infos" : [ {
        "input_path" : "OBS://bucket/dir/",
        "output_path" : "OBS://bucket/dir/",
        "env_var_name" : "string"
      } ]
    }
  }
}

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: 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

202

Endpoint details are queried.

400

BadRequest

401

Unauthorized

403

Forbidden

408

Request Time-out

500

InternalServerError

Error Codes

See Error Codes.