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
namestringswift-falcon.local.cpuCoresintegerrequiredmemoryGbintegerrequiredstorageGbintegerrequiredregionstringrequiredid 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
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.
{ "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
statusstringprovisioning. The VPS is still being built. One of provisioning.vpsIdstring or nullvps_…). null when the VPS is not in the account yet.orderIdstringord_…).invoiceIdstringinv_…).deploymentobjectnamestringregionstringregions.resourcesobjectcpuCoresintegermemoryGbintegerstorageGbintegerErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The 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. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The 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. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |