Help Center/ CodeArts Deploy/ API Reference (Ally Region)/ APIs/ Managing Hosts/ Creating a Host (Recommended)
Updated on 2026-01-08 GMT+08:00
Online Debugging
CLI Examples
Share

Creating a Host (Recommended)

Function

This API is used to create a host in a specified host cluster.

Calling Method

For details, see Calling APIs.

URI

POST /v1/resources/host-groups/{group_id}/hosts

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

group_id

Yes

String

Definition:

Host cluster ID.

Constraints:

N/A.

Value range:

32 characters, including letters and digits.

Default value:

N/A.

Request Parameters

Table 2 Request header parameters

Parameter

Mandatory

Type

Description

Content-Type

Yes

String

Definition:

Type (or format) of the message body.

Constraints:

N/A.

Value range:

N/A.

Default value:

N/A.

X-Auth-Token

Yes

String

Definition:

User token. Obtain a token (the value of the X-Subject-Token response header) by calling the IAM API used for.

Constraints:

N/A.

Value range:

String. Max. 20,000 characters.

Default value:

N/A.
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

host_name

Yes

String

Definition:

Host name.

Constraints:

N/A.

Value range:

3 to 128 characters, including letters, digits, hyphens (-), underscores (_), and periods (.).

Default value:

N/A.

ip

Yes

String

Definition:

Host IP address.

Constraints:

N/A.

Value range:

N/A.

Default value:

N/A.

port

Yes

Integer

Definition:

SSH port of the host.

Constraints:

N/A.

Value range:

0–65535.

Default value:

N/A.

os

Yes

String

Definition:

Host OS type.

Constraints:

N/A.

Value range:

  • window: Windows OS.

  • linux: Linux OS.

Default value:

N/A.

as_proxy

Yes

Boolean

Definition:

Agent or not.

Constraints:

N/A.

Value range:

  • true: Yes.

  • false: No.

Default value:

N/A.

proxy_host_id

No

String

Definition:

Agent ID.

Constraints:

N/A.

Value range:

32 characters, including letters and digits.

Default value:

N/A.

authorization

Yes

HostAuthorizationRequestBody object

Parameter description:

Host login authentication. You can use a password or key to log in.

Constraints:

N/A.

install_icagent

No

Boolean

Definition:

Whether to install ICAgent.

Constraints:

N/A.

Value range:

  • true: Yes.

  • false: No.

Default value:

N/A.
Table 4 HostAuthorizationRequestBody

Parameter

Mandatory

Type

Description

username

Yes

String

Parameter description:

Username for host login.

Constraints:

N/A.

Value range:

1 to 31 characters, including letters, digits, underscores (_), hyphens (-), periods (.), and at signs (@).

Default value:

N/A.

password

No

String

Parameter description:

Password. Mandatory when the authentication type is 0.

Constraints:

N/A.

Value range:

5 to 32 characters, excluding spaces, newline characters, carriage return characters, tab characters, double quotation marks (""), and single quotation marks ('').

Default value:

N/A.

private_key

No

String

Parameter description:

Key. Mandatory when the authentication type is 1.

Constraints:

N/A.

Value range:

Max. 5,000 characters.

Default value:

N/A.

trusted_type

Yes

Integer

Parameter description:

Authentication type for host login.

Constraints:

N/A.

Value range:

  • 0: password authentication.

  • 1: key authentication. Default value:

0.

Response Parameters

Status code: 200

Table 5 Response body parameters

Parameter

Type

Description

status

String

Definition:

Request status (successful or failed).

Value range:

  • success: Successful.

  • failed: Failed.

id

String

Definition:

Host ID.

Value range:

32 characters, including letters and digits.

Example Requests

When creating a host, you need to enter the basic information about the host, including the host name, IP address, port number, username, and password.

https://{endpoint}/v1/resources/host-groups/ab7647b0863c4e969c8949d38d591339/hosts

{
  "host_name" : "100.101.28.215",
  "ip" : "100.101.28.215",
  "port" : "22",
  "os" : "linux",
  "as_proxy" : false,
  "proxy_host_id" : "",
  "authorization" : {
    "username" : "root",
    "password" : "*****",
    "private_key" : "",
    "trusted_type" : 0
  },
  "install_icagent" : true
}

Example Responses

Status code: 200

OK: The request is successful.

{
  "status" : "success",
  "id" : "300d6d2e53624d0da08b182099ad10f7"
}

Status Codes

Status Code

Description

200

OK: The request is successful.

Error Codes

See Error Codes.

Parent topic: Managing Hosts