Help Center/ DataArts Fabric/ API Reference/ APIs/ Endpoint Management/ Creating an Endpoint

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

View PDF

Creating an Endpoint

Function

This API is used to create an endpoint. You can call this API to create an endpoint within a workspace. You need to enter information like the name, description, type, resource configuration, and CAP configuration. The endpoint information will then be returned. This is an asynchronous API. It is used in conjunction with the ShowEndpoint API to query details about an endpoint, with no specific scenarios involved.

URI

POST /v1/workspaces/{workspace_id}/endpoints

**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.

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	Yes	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: N/A. Default Value: N/A.
type	Yes	String	Definition: Endpoint type. Constraints: N/A. Range: service: Service endpoint, indicating a resource group that can receive service requests. ray: Endpoint of a Ray cluster on Kubernetes, indicating a Ray cluster. inference: Inference endpoint, indicating an inference function instance. job: Job endpoint, indicating a resource group that can receive job requests. ray_service: Endpoint of a Ray service on Kubernetes, indicating a Ray service. sql: SQL endpoint, indicating a resource group that can receive SQL requests. 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.
cache_list	No	Array of CacheConfig objects	Definition: Distributed cache 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: false.

**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.

**Table 27** CacheConfig
Parameter	Mandatory	Type	Description
mnt_path	Yes	String	Definition: Mount path. Constraints: N/A. Range: N/A. Default Value: N/A.
cache_ins_id	Yes	String	Definition: Distributed cache ID. Constraints: N/A. Range: ID of a created distributed cache resource. Default Value: N/A.

Response Parameters

Status code: 202

Endpoint details are queried.

Status code: 400

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

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

**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.

Status code: 500

**Table 31** 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 an endpoint. The specifications are shown in the example.

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

{
  "name" : "endpoint1",
  "description" : "description",
  "type" : "job",
  "reserved_resource" : {
    "apu" : {
      "spec_code" : "dpu.d1x",
      "warm_up_num" : 1,
      "max_num" : 100
    },
    "dpu" : {
      "spec_code" : "dpu.d1x",
      "warm_up_num" : 4,
      "max_num" : 100
    },
    "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" : {
      "log_config" : {
        "lts" : {
          "enabled" : true,
          "log_group_id" : "string",
          "log_stream_id" : "string"
        }
      },
      "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/"
      } ]
    }
  },
  "cache_list" : [ {
    "mnt_path" : "string",
    "cache_ins_id" : "string"
  } ]
}

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-17T01:12:24.663Z"
  },
  "runtime_env_type" : "RELEASE",
  "config" : {
    "ray_service_config" : {
      "log_config" : {
        "lts" : {
          "enabled" : true,
          "log_group_id" : "string",
          "log_stream_id" : "string"
        }
      },
      "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.

Parent topic: Endpoint Management

Previous topic: Querying the Endpoint List

Next topic: Querying Details About an Endpoint

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot