Layerbeat

Buy a server

POST
/v1/vms

Creates a VPS using your personal credit and returns an operation to track deployment. Keep the same Idempotency-Key when retrying.

Access: API key: vm:write · Session: developer, admin or owner.

Authorization

headerAuthorizationBearer <token>

Send Authorization: Bearer <token>. A token is an API key (lb_live_…, scoped, for programs) or a session (lb_sess_…, from signup or login, for people). See Authentication above.

Header Parameters

Idempotency-Key?string

A unique string (for example a UUID). Repeating the same request with the same key returns the original result instead of buying again.

X-Org-ID?string

Sessions only: act on this organization (you must be a member). Default: your first organization.

Request Body

application/json
  1. body
currency?string

Selected personal credit balance. Never converts or combines balances.

Value in"USD""IDR"
name*string

Letters, digits, ., _, -; starts with a letter or digit; up to 63 characters.

Match^[a-zA-Z0-9][a-zA-Z0-9._-]{0,62}$
region*string
plan*string
image*string
term_months*integer

Prepaid term in months.

Range1 <= value
quote_id?string

Optional: honour the price of a quote.

ssh_key_ids?array<string>

Required for SSH key login (1 to 10); omit or use an empty array for password login. The combined first-boot payload must fit the server's creation limit; oversized selections return 400 before credit is reserved. Ed25519 keys are recommended.

Items0 <= items <= 10
auth?string

Defaults to ssh_key. Password modes require no SSH keys. Random passwords are generated by Layerbeat and retrieved explicitly after provisioning.

Value in"ssh_key""custom_password""random_password"
password?string

Required only for custom_password. Use ASCII letters, numbers or ()`~!@#$%^&*-+=_ and at least three of uppercase, lowercase, numbers and symbols. Never returned in ordinary API responses.

Length12 <= length <= 30
auto_renew?boolean

Default false. Explicit true authorizes renewal for this term up to the purchase price; update the limit using the renewal settings endpoint.

Defaultfalse
payment_method?"wallet"

Spend available Layerbeat credit. Omit this field or use wallet. Fund credit separately using the top-up endpoint.

Value in"wallet"
tags?

Up to 10 free-form labels.

Propertiesproperties <= 10

Response Body

Accepted: available credit is reserved and asynchronous creation has started

application/json
  1. response

The purchased VM and its asynchronous operation. Creation always spends available credit.

vm*
operation*
curl -X POST 'https://layerbeat.com/v1/vms' \  -H 'Idempotency-Key: 7c1f1b0e-6f0c-4a5e-9c33-2d0c0f1c9a11' \  -H 'Content-Type: application/json' \  -d '{  "name": "web-1",  "region": "sgp",  "plan": "small",  "image": "ubuntu-24-04",  "term_months": 1,  "ssh_key_ids": [    "key_m2q8vx4zt7kd5wn3bj6hf9cpra"  ]}'
{  "vm": {    "id": "vm_gnkrp6zuxvsqki7sqxeluvsw2y",    "name": "web-1",    "status": "provisioning",    "region": "sgp",    "plan": "small",    "image": "ubuntu-24-04",    "ipv4": null,    "ipv6": null,    "vcpu": 2,    "memory_mb": 2048,    "disk_gb": 60,    "created_at": "2026-10-01T10:00:00Z",    "expires_at": null,    "auto_renew": true,    "ssh_key_ids": [      "key_m2q8vx4zt7kd5wn3bj6hf9cpra"    ],    "tags": {}  },  "operation": {    "id": "op_4yw4xmradad4bstgr4d5qtreb4",    "type": "vm.create",    "status": "pending",    "vm_id": "vm_gnkrp6zuxvsqki7sqxeluvsw2y",    "steps": [      {        "name": "payment_reserved",        "status": "succeeded"      },      {        "name": "creating_instance",        "status": "running"      },      {        "name": "booting",        "status": "pending"      },      {        "name": "ready",        "status": "pending"      }    ],    "result": null,    "error": null,    "created_at": "2026-10-01T10:00:00Z",    "finished_at": null  }}