Creating a VPS

Creating an instance via the API is equivalent to placing an order in the panel: it charges your quicksrv wallet and queues the server for provisioning.

1. Find a plan

List the plans you can deploy:

curl https://api.prod.quicksrv.io/api/v1/services \
  -H "Authorization: Bearer qsk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

[
  { "id": 12, "name": "VPS S", "slug": "vps-s", "price": 5.0,
    "billing_cycle": "monthly", "category": "vps",
    "specs": { "vcpu": 2, "ram": "4 GB", "storage": "80 GB NVMe", "traffic": "Fair use" } }
]

Each plan carries a structured specs object so you can size your deployment programmatically. vcpu is an integer; ram, storage and traffic are strings that include their units. Any field may be null if the plan does not declare it, and traffic is the monthly data-transfer allowance — not the DDoS-mitigation figure quoted in marketing.

2. Find the available OS slugs

The os field takes an OS slug. The slugs valid for a given plan depend on its data centre, so list them per plan:

curl https://api.prod.quicksrv.io/api/v1/services/12/os-options \
  -H "Authorization: Bearer qsk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "location_label": "Amsterdam, NL",
  "os_options": [
    { "slug": "ubuntu-24.04", "label": "Ubuntu", "version": "24.04 LTS", "os_id": 1001 },
    { "slug": "debian-12",    "label": "Debian", "version": "12",        "os_id": 1002 },
    { "slug": "rocky-9",      "label": "Rocky Linux", "version": "9",    "os_id": 1003 }
  ]
}

Use one of the returned slug values for the os field below. (If you omit os, the plan’s default image is installed.)

3. Create the instance

Requires the vps:create scope.

curl -X POST https://api.prod.quicksrv.io/api/v1/instances \
  -H "Authorization: Bearer qsk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0c9e-2c1a-4f8e-9b2a-1d2e3f4a5b6c" \
  -d '{
    "service_id": 12,
    "hostname": "web-01.example.com",
    "os": "ubuntu-24.04",
    "ssh_pubkey": "ssh-ed25519 AAAA... you@example.com"
  }'

Request fields

Field	Required	Description
`service_id`	yes	Plan to deploy (from `GET /services`).
`hostname`	no	Desired hostname.
`os`	no	OS slug to install (e.g. `ubuntu-24.04`).
`ssh_pubkey`	no	Public SSH key to inject (Linux only).
`root_password`	no	Initial root/Administrator password. Auto-generated if omitted.
`coupon_code`	no	Discount coupon applied at checkout.

A successful call returns 201 Created with the new instance. Provisioning is asynchronous: the instance is created immediately but provider_id/ipv4 are populated once the server finishes deploying (usually a minute or two). Poll GET /instances/{id} until they appear.

Test it first (dry run)

To validate a request and preview the wallet charge without creating, charging, or provisioning anything, add ?dry_run=true:

curl -X POST "https://api.prod.quicksrv.io/api/v1/instances?dry_run=true" \
  -H "Authorization: Bearer qsk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service_id": 12, "os": "ubuntu-24.04"}'

{
  "dry_run": true,
  "would_create": true,
  "service_id": 12,
  "plan_name": "VPS S",
  "billing_cycle": "monthly",
  "charge_amount": 5.0,
  "discount_amount": 0.0,
  "currency": "EUR",
  "wallet_balance": 3.0,
  "sufficient_funds": false
}

A dry run returns 200 (not 201), validates the plan, applies any coupon, and tells you whether your wallet can cover the charge — perfect for CI and integration tests.

Idempotency

Network blips happen. Send a unique Idempotency-Key header and a retried request with the same key returns the original instance instead of creating (and charging for) another one.

Use a fresh UUID per logical create.
Keys are scoped to the API key that created them.

Errors you may see

Status	Meaning
`402`	Wallet balance too low. Top up and retry.
`404`	`service_id` not found or inactive.
`400`	The plan is not a VPS/dedicated plan.
`403`	Your key lacks the `vps:create` scope.
`429`	Create rate limit exceeded (see Rate limits).

Next: Managing instances →