Skip to content

Create a Cloud VPS

POST /api/v2/vps/payg/deployments

Creates a pay-as-you-go Cloud VPS with the CPU, memory and disk you choose. Check actions.canDeploy.allowed on GET /api/v2/vps/payg/deployments first. Pick a size inside limits there (the range for one Cloud VPS) and a region from regions. Keep the account inside remaining on GET /api/v2/vps/payg/limits. The call does not check those limits today. Ask for more with POST /api/v2/vps/payg/limits/requests. Fixed-term VPS plans are ordered with POST /api/v2/orders instead.

The call creates an order and an invoice. The VPS is billed by the hour at the prices in pricing from GET /api/v2/vps/payg/deployments. It returns 201 with status: provisioning while the VPS is built in the background. Follow the VPS with GET /api/v2/vps/{id} using vpsId. When vpsId is null, the VPS is not in the account yet. It shows up in GET /api/v2/vps a little later. Sending the same request again creates a second VPS. A 500 or a timeout can come after the order was placed. Look for the VPS by name in GET /api/v2/vps before you send the request again. Send your own name so you can find it.

The request has no field for the operating system or an SSH key. Sign in with the root password in access.rootPassword on GET /api/v2/vps/{id}/details.

Authentication: An API key with the scope write:billing. About keys and scopes

Request

Body

namestring
Hostname of the new VPS, 3 to 253 characters: letters, digits, hyphens and dots. It is stored in lowercase. Default: a generated name such as swift-falcon.local.
cpuCoresintegerrequired
CPU cores. 1 to 32.
memoryGbintegerrequired
Memory in GB. 1 to 256.
storageGbintegerrequired
Disk size in GB. 50 to 2000.
regionstringrequired
Region id from regions on GET /api/v2/vps/payg/deployments. Today any other value is also accepted and echoed in deployment.region. It does not change where the VPS is built.

Example

POST /api/v2/vps/payg/deployments
curl -X POST "https://cloud.hostup.se/api/v2/vps/payg/deployments" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cpuCores": 2,
"memoryGb": 4,
"storageGb": 80,
"region": "stockholm"
}'

Responses

201 The Cloud VPS is being created.

Response 201
{
"status": "provisioning",
"vpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"orderId": "ord_01hxa3b4c5d6e7f8g9h0j1k2m3",
"invoiceId": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
"deployment": {
"name": "swift-falcon.local",
"region": "stockholm",
"resources": {
"cpuCores": 2,
"memoryGb": 4,
"storageGb": 80
}
}
}
Response fields
statusstring
Always provisioning. The VPS is still being built. One of provisioning.
vpsIdstring or null
ID of the new VPS (vps_…). null when the VPS is not in the account yet.
orderIdstring
ID of the order (ord_…).
invoiceIdstring
ID of the invoice made with the order (inv_…).
deploymentobject
What was created.
namestring
Hostname of the new VPS.
regionstring
Region as sent. It is not checked against regions.
resourcesobject
Size as sent.
cpuCoresinteger
CPU cores.
memoryGbinteger
Memory in GB.
storageGbinteger
Disk size in GB.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400The body is invalid: an unknown field, a size outside its range or not a whole number, a bad name, or no region. errors[].pointer names the field, for example /cpuCores.
401Unauthorized. Authentication is required.
403The account cannot create a Cloud VPS now. code names the main blocker: country_not_supported, insufficient_trusted_history, no_card_on_file, not_verified or no_cloud_access. blockerReasons lists every blocker and actions.canDeploy.reason explains it. payg_payment_overdue means a pay-as-you-go invoice is overdue. Pay it first. A contact’s API key also gets 403 without permission to place orders.
404Not found. The resource does not exist or is not owned by the caller.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.