VPS API
Create, run and manage virtual servers over HTTP with a Helipod API key.
The VPS API lets you do from code what you do on the VPS pages of the dashboard: pick a plan, create a server, power it on and off, reinstall it, manage its firewall, ports and SSH keys, read its metrics, take snapshots, set up backups and renew it.
Base URL
https://api.helipod.io/apiVPS routes live under /vps, for example https://api.helipod.io/api/vps/plans. The backup plan catalogue is the one exception and lives at /backup/plans.
Authentication
Every request needs a Helipod API key in the Authorization header:
Authorization: Bearer hel_your_keyCreate keys in the dashboard under Project → Settings → API keys. The full key is shown once, when you create it. An account can hold up to 10 active keys.
A key lists the products it may use: vps, containers, domains, databases, email, ai and account. The VPS API needs vps. A key without it gets 403 with code SCOPE_NOT_ALLOWED on every VPS route. Create a new key with VPS API enabled.
A key is either limited to one project or covers the whole account (every project the key owner owns).
- A project key only sees servers in its project. Listing always filters to that project, and creating a server in another project fails.
- An account key sees every server of the owner. It can narrow a list with
?projectId=.
Anything outside the key's reach answers 404, never 403, so a request cannot be used to find out whether an id exists.
A missing header answers 401 NO_API_KEY, an unknown or revoked key 401 INVALID_API_KEY, and a key past its expiry date 401 API_KEY_EXPIRED.
Response envelope
Every response is JSON in the same envelope.
{
"success": true,
"data": { "id": "1f757fd5-98d1-490a-81a0-58b5798a5815", "status": "running" }
}Branch on code, show error to people. Every code is listed on Errors. Lists are returned whole, without pagination.
Rate limit
Each key may make 10 requests per second, with a burst of up to 10. The allowance refills continuously, so after one idle second a key has its full allowance back. The limit is per key and shared by every API the key calls on api.helipod.io (VPS, Container, Database, Domain, Account and AI API).
Every response carries the current state:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per second (10) |
X-RateLimit-Remaining | Requests left right now |
Retry-After | Only on a refused request: seconds to wait |
A request over the limit is refused with code RATE_LIMITED (status 429). Wait for Retry-After seconds and retry.
Money
Paid actions are charged to the wallet of the key owner (the deposit balance, in Rupiah) at the moment you call them. If the balance is too low the call fails with 402 INSUFFICIENT_BALANCE and nothing is created or changed. These endpoints charge the wallet:
| Endpoint | Charge |
|---|---|
POST /vps | The full price of the chosen period |
POST /vps/:id/renew | The price of the renewal period |
POST /vps/:id/upgrade | The prorated difference for the days left |
POST /vps/:id/backup | The backup plan price for the first period |
PATCH /vps/:id/backup with a larger planCode | The prorated difference for the time left |
With auto-renew on (the default), a VPS and its backup plan also renew themselves from the wallet before they expire. If a create, renewal or upgrade fails after the charge, the amount is refunded to the wallet automatically, once.
The VPS API has no dryRun mode and does not read an Idempotency-Key header. A retried POST /vps creates and charges a second server, so check GET /vps before you retry a create that timed out. Use GET /vps/plans and GET /vps/:id/renewal-options to see prices before you buy.
Asynchronous by design
Calls that change a server queue the work and return straight away. The response shows the server in a transitional status such as provisioning, stopping or restarting. Poll GET /vps/:id until the status settles on running, stopped or error. While a server is busy, other changes to it answer 409 VPS_BUSY. See Instance statuses.
Quick start
Create a key
In the dashboard open Project → Settings → API keys, create a key with VPS API enabled and copy it. Note the id of the project the server should belong to.
Pick a plan and an operating system
curl https://api.helipod.io/api/vps/plans \
-H "Authorization: Bearer hel_your_key"Take a plan id and one entry of its osTemplates, for example ubuntu-24.04.
Create the server
curl -X POST https://api.helipod.io/api/vps \
-H "Authorization: Bearer hel_your_key" \
-H "Content-Type: application/json" \
-d '{
"planId": "4db565ff-782f-46c8-9324-e4670517233f",
"projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"name": "web-1",
"osType": "ubuntu",
"osVersion": "24.04",
"rootPassword": "Str0ng!Passw0rd",
"billingPeriod": "monthly"
}'The wallet is charged and the server comes back with status: "provisioning".
Wait until it runs
curl https://api.helipod.io/api/vps/1f757fd5-98d1-490a-81a0-58b5798a5815 \
-H "Authorization: Bearer hel_your_key"Repeat every few seconds until status is running. publicIp then holds the server's address.
What you can do
Plans
List plans with specs, operating systems and the price you pay.
Instances
Create, list, inspect, rename and terminate servers. Metrics, statuses and polling.
Actions
Start, stop, restart, reinstall, reset the root password, read login details.
Billing
Renewal prices, renew, upgrade options and upgrades, auto-renew.
Snapshots
Take a snapshot of the disk and roll back to it.
Firewall
Open and close inbound ports.
Port forwarding
TCP and UDP ports and HTTP or HTTPS domain routes, on servers that share an address.
SSH keys and access
Add and remove root's SSH keys, switch SSH on or off.
Backups
Nightly backups as an add-on: restore files or the whole server, download archives.
Errors
Every error code with its status and meaning.