HELPER VPS

VPS API quick start: create an API key and your first server

The HELPER VPS API is a REST API that exchanges JSON over HTTPS. With a single key you can list plans, create servers, control power, renew and delete. Follow along from your first request to creating and deleting a server.

Step 1. Create an API key

You can create an API key after your first payment. See the USDT payment guide for how to pay.

  • Click Create API key in the API keys menu of your account.
  • A key starting with hvp_ is shown only once. Copy it right away and save it in a password manager.
  • Only the last characters of the key stay on screen, so you can tell which key you are using.
  • Clicking Create new key gives you a new key and disables the old one at once.

The key unlocks your whole account, so keep it out of code repositories and screen shares by putting it in an environment variable. The examples in this guide start by storing the key in a variable in the terminal.

Terminal
export HVP_KEY=hvp_your_key_here
export HVP=https://helpervps.com/api/v1

Step 2. Authentication and your first request

Send every request under the base address https://helpervps.com/api/v1 with the header Authorization: Bearer KEY. As your first request, load your server list. If you have no servers, an empty list [] comes back.

Terminal
curl -s $HVP/servers -H "Authorization: Bearer $HVP_KEY"

Each account can send up to 300 requests per minute, and server creation is limited to 10 per 10 minutes. For repeated status checks, a few seconds between requests is plenty. All responses are JSON, and errors come back with a status code in the form {"error": "code"}.

Step 3. Choose a plan, region and image

Every value you use to create a server comes from the catalog. GET /catalog returns the plans, locations, images and addons on sale in one call. With jq, it is easy to pick out just the parts you need.

Terminal
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.plans[] | {code, type, vcpu, ram_mb, disk_gb, monthly}'
curl -s $HVP/catalog -H "Authorization: Bearer $HVP_KEY" | jq '.locations, .images'
  • Plan codes: such as s1 and s2, indicating type and size. type is basic (standard SSD), fast (high-performance NVMe), cpu (dedicated CPU) or mem (high memory). monthly is the monthly price in US dollars.
  • Location codes: city names such as frankfurt, singapore and seoul.
  • Image codes: operating systems such as ubuntu-24-04, debian-13 and almalinux-10, and apps such as app-docker and app-wordpress.
  • Addons: the automatic backups rate, extra disk sizes and price per GB, and the DDoS protection price. Options not on sale come back as null.

If jq is missing, install it with apt install -y jq on Ubuntu or brew install jq on Mac. It is the same list you choose from on the website, so the pricing page is handy for seeing the differences between plans.

Step 4. Create a server

Send the plan, location, image and name as JSON to POST /servers. Pay for the first term of your chosen plan and server creation begins.

Terminal
curl -s -X POST $HVP/servers \
  -H "Authorization: Bearer $HVP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"s2","location":"frankfurt","image":"ubuntu-24-04","label":"web-1"}'

On success you get status code 201 with the server details. id is the server code in the form S-XXXX-XXXX-XXXX, used in every request from then on. root_password is included once in this response, so save it right away. You can also see it on the server page for 7 days.

  • label: the server name. Up to 40 Latin letters, digits, dots and hyphens; other characters become hyphens.
  • backups: true turns on automatic backups.
  • extra_disk_gb: the size of an extra NVMe block disk. Use one of the catalog's sizes_gb values (50, 100, 250, 500, 1000).
  • ddos_protection: true turns on DDoS protection.

Option prices are added to the server's monthly price and shown in monthly in the response, renewing automatically at the same amount on each billing date. Each account can create up to 10 servers.

Step 5. Check status and connect

A new server starts as creating, becomes running when ready, and gets its ipv4 address filled in. The loop below checks the status every 10 seconds and shows the IP once it is running. Replace the server code with your own server's code.

Terminal
ID=S-XXXX-XXXX-XXXX
until [ "$(curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .state)" = "running" ]; do sleep 10; done
curl -s $HVP/servers/$ID -H "Authorization: Bearer $HVP_KEY" | jq -r .ipv4

The status is one of creating, running, stopped, rebooting, installing, suspended or check. suspended means the server was paused because it was not renewed on the billing date, and check means we are checking the result of server setup. Once the IP appears, connect with ssh root@IP. How to connect is in the first login guide.

Step 6. Power, renewal and deletion

Terminal
curl -s -X POST $HVP/servers/$ID/stop   -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/start  -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/reboot -H "Authorization: Bearer $HVP_KEY"
curl -s -X POST $HVP/servers/$ID/renew  -H "Authorization: Bearer $HVP_KEY"
curl -s -X DELETE $HVP/servers/$ID     -H "Authorization: Bearer $HVP_KEY"
  • start: turns on a stopped server.
  • stop, reboot: turns off or restarts a running server.
  • renew: pays for 1, 3, 6 or 12 more months now. A suspended server comes back with this request too.
  • DELETE: deletes the server and its disks and returns {"state": "deleted"}. The remaining time of a month already paid is not refunded.

Sending an action that is not possible in the current state returns 409 wrong_state, for example sending start to a server that is already on. Reinstalling and creating a new root password are done on the server page; the steps are in the reinstall guide.

Run the same steps in Python

Written as a Python script, the same flow looks like this. It uses the requests library (pip install requests).

create_server.py
import os, time, requests

API = "https://helpervps.com/api/v1"
H = {"Authorization": f"Bearer {os.environ['HVP_KEY']}"}

r = requests.post(f"{API}/servers", headers=H, json={
    "plan": "s2", "location": "frankfurt",
    "image": "ubuntu-24-04", "label": "web-1",
})
r.raise_for_status()
server = r.json()
print("id:", server["id"], "root password:", server["root_password"])

while True:
    s = requests.get(f"{API}/servers/{server['id']}", headers=H).json()
    if s["state"] == "running" and s["ipv4"]:
        print("ready:", s["ipv4"])
        break
    time.sleep(10)

Common error codes

  • 401 unauthorized: the key is missing or wrong. Check that the header looks like Authorization: Bearer hvp_....
  • 403 not_allowed: opens once your first payment is confirmed.
  • 400 bad_request: a field name or value is wrong. Use codes exactly as they appear in the catalog.
  • 402 not_enough_balance: the payment amount is below $25. Send again with at least $25.
  • 409 limit: you have reached the number of servers your account can create.
  • 409 not_created: the server could not be created, and the fee goes to your account credit.
  • 202 checking: we are checking the result of server setup. Do not send the same request again; check your server list. The server will be completed or the fee returned to your account credit.
  • 404 not_found: a server code or path that is not in your account.
  • 409 wrong_state: an action that is not possible in the current state.
  • 429 rate_limited: you have reached the per-minute request limit. Wait a moment and send again.

All endpoints, response fields and examples are collected in the API docs. See what you can do with the API and how it is used on the VPS API page.

Related guides

Settings worth doing right after this guide.

View all guides