Help Center/Elastic Cloud Server/API Reference/APIs/NIC Management/Adding NICs to an ECS in a Batch
Updated on 2026-03-19 GMT+08:00
View PDF
Share

Adding NICs to an ECS in a Batch

Function

This API is used to add one or multiple NICs to an ECS.

This API is an asynchronous API. After the NIC addition request is successfully delivered, a job ID is returned. This does not mean the NIC addition is complete. You need to call the API by referring to Querying Job Execution Status to query the job status. The SUCCESS status indicates that the NIC addition is successful.

Constraints

Do not detach or delete the NICs that are being added.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned.
  • If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
  • If you are using identity policy-based authorization, the permissions listed below are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

ecs:cloudServers:addNics

write

instance *

  • ecs:SubnetId
  • ecs:PortId

-

-

URI

POST /v1/{project_id}/cloudservers/{server_id}/nics

Table 1 describes the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Definition

Specifies the project ID.

For details about how to obtain the ID, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

server_id

Yes

Definition

Specifies the ECS ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Request

Table 2 describes the request parameters.
Table 2 Request parameters

Parameter

Mandatory

Type

Description

nics

Yes

Array of objects

Definition

Specifies the NICs to be added. For details, see Table 3.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 3 nics field description

Parameter

Mandatory

Type

Description

subnet_id

No

String

Definition

Specifies the information about the NICs to be added to an ECS.

The value must be the ID of a created network in UUID format.

Constraints

N/A

Range

N/A

Default Value

N/A

security_groups

No

Array of objects

Definition

Specifies the security groups for NICs. For details, see Table 4.

Constraints

N/A

Range

N/A

Default Value

N/A

ip_address

No

String

Definition

Specifies the IP address.

Constraints

N/A

Range

If this parameter is empty, the IP address is automatically assigned.

Default Value

N/A

port_id

No

String

Definition

Specifies the NIC ID in UUID format.

You can obtain the NIC ID using the VPC API for querying ports.

Constraints

  • Either port_id or subnet_id must be specified.
  • The NIC must be in DOWN state.
  • If both port_id and subnet_id are specified, port_id is used preferentially.
  • If port_id is not empty, an elastic network interface is used. In this case, neither security_groups nor ip_address takes effect.

Range

If this parameter is not empty, the specified NIC is attached.

Default Value

N/A

ipv6_enable

No

Boolean

Definition

Specifies whether IPv6 is supported.

Constraints

N/A

Range

If this parameter is set to true, the NIC supports IPv6.

Default Value

N/A

ipv6_bandwidth

No

Object

Definition

Specifies the bound shared bandwidth. For details, see ipv6_bandwidth Field Description.

Constraints

N/A

Range

N/A

Default Value

N/A

Table 4 security_groups field description

Parameter

Mandatory

Type

Description

id

Yes

String

Definition

Specifies the ID of the security group.

Constraints

N/A

Range

N/A

Default Value

N/A

Response

Table 5 describes the response parameters.

Table 5 Response parameters

Parameter

Type

Description

job_id

String

Definition

Specifies the job ID returned after a job is delivered. The job ID can be used to query the job execution progress. For details about how to query the job execution status based on job_id, see Job Status Management.

Range

N/A

For details about abnormal responses, see Responses (Jobs).

Example Request

Add the NIC whose ID is d32019d3-bc6e-4319-9c1d-6722fc136a23 and security group ID is f0ac4394-7e4a-4409-9701-ba8be283dbc3 to an ECS.

POST https://{endpoint}/v1/{project_id}/cloudservers/{server_id}/nics

{
    "nics": [
        {
            "subnet_id": "d32019d3-bc6e-4319-9c1d-6722fc136a23", 
            "security_groups": [
                {
                    "id": "f0ac4394-7e4a-4409-9701-ba8be283dbc3"
                }
            ]
        }
    ]
}

Example Response

{      
    "job_id": "ff80808288d41e1b018990260955686a" 
}

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.

Parent topic:NIC Management