Help Center/ Dedicated Host/ API Reference/ API/ Allocating DeHs
Updated on 2026-02-27 GMT+08:00
View PDF
Share

Allocating DeHs

Function

This API is used to allocate one or more DeHs and set required parameters, such as the flavor, AZ, and quantity.

Constraints

The number of allocatable DeHs depends on the DeH quota owned by the tenant.

Authorization

Your account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned. For the specific permissions required, see Introduction.

URI

POST /v1.0/{project_id}/dedicated-hosts

Table 1 describes the parameters.

Table 1 Parameter description

Parameter

Type

Mandatory

Description

project_id

String

Yes

Specifies the project ID.

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

Request

Table 2 Request parameters

Parameter

Location

Type

Mandatory

Description

name

body

String

Yes

Specifies the DeH name.

It can contain 1 to 255 characters. Only letters, digits, underscores (_), hyphens (-), and periods (.) are allowed.

auto_placement

body

String

No

Specifies whether to allow an ECS to be placed on any available DeH if its DeH ID is not specified during its creation.

The value can be on or off.

The default value is on.

availability_zone

body

String

Yes

Specifies the AZ to which the DeH belongs.

It can contain up to 255 characters.

host_type

body

String

Yes

Specifies the DeH type.

For details, see Categories and Types > Overview.

quantity

body

Integer

Yes

Specifies the number of allocatable DeHs.

tags

body

Array of objects

No

Specifies the DeH tags.

For details, see Table 3.

extend_param

body

Object

No

Specifies the extended DeH attributes.

For details, see Table 4.
Table 3 tag field description

Parameter

Type

Mandatory

Description

key

String

Yes

Specifies the tag key.

  • It contains a maximum of 36 Unicode characters.
  • The value cannot be empty.
  • It cannot contain the following ASCII characters: =*<>\|/,

value

String

Yes

Specifies the tag value.

  • It contains a maximum of 43 Unicode characters.
  • It cannot contain the following ASCII characters: =*<>\|/,
Table 4 extend_param field description

Parameter

Type

Mandatory

Description

charging_mode

String

No

Specifies the DeH billing mode.

prePaid: Yearly/monthly

period_type

String

No

Specifies the subscription period. This parameter is valid only when charging_mode is set to prePaid.

  • month: Monthly
  • year: Yearly

period_num

Integer

No

Specifies the number of subscription periods.

The value is an integer greater than 0. This parameter is valid and mandatory only when charging_mode is set to prePaid.

  • If periodType is month, the value is an integer from 1 to 9.
  • If periodType is year, the value is an integer from 1 to 3.

is_auto_pay

Boolean

No

Specifies whether to enable automatic payment.

  • true: The order will be automatically paid.
  • false: You must manually pay the order.

is_auto_renew

Boolean

No

Specifies whether to enable auto-renewal.

  • true: Auto renewal is enabled.
  • false: Auto renewal is disabled.

enterprise_project_id

String

No

Specifies the ID of the enterprise project.

Response

Table 5 Response parameters

Parameter

Location

Type

Description

job_id

body

String

Specifies the job ID returned after a job is delivered. The job ID can be used to query the job execution progress.

order_id

body

String

Specifies the order ID. This parameter is returned for the creation of a yearly/monthly DeH.

Example Request

Two s3 DeHs are allocated in az1, and the DeH name is General Computing server1. 
POST https://{Endpoint}/v1.0/9c53a566cb3443ab910cf0daebca90c4/dedicated-hosts
{
     "availability_zone": "dc1.az1",
     "name": "General Computing server1",
     "auto_placement": "off",
     "host_type": "c4",
     "quantity": 2,
     "tags": [
         {
             "key": "key1",
             "value": "value1"
         }
     ],
     "extend_param": {
         "enterprise_project_id": "f8e0ecc8-3825-4ee8-9596-fb4258ffdcbb"
     }
}

Example Response

{
    "job_id": "ff808082739334d80173943ec9b42130",
    "order_id": "CS2007281506xxxxx"
}

Status Code

Table 6 Returned error codes

Error Code

Description

403 Forbidden
  1. Insufficient quota.
  2. The flavor is not supported.

404 FlavorNotFound

Invalid flavor.

For more status codes, see Status Codes.

Parent topic: API