Panduan cepat API VPS, membuat API key dan server pertama

Langkah 2. Autentikasi dan permintaan pertama

Semua permintaan dikirim ke alamat dasar https://helpervps.com/api/v1, dengan header Authorization: Bearer API_KEY. Sebagai permintaan pertama, ambil daftar server Anda. Jika belum ada server, daftar kosong [] dikembalikan.

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

Setiap akun bisa mengirim hingga 300 permintaan per menit, dan pembuatan server hingga 10 kali per 10 menit. Untuk permintaan berulang yang memeriksa status, jeda beberapa detik sudah cukup. Semua respons berupa JSON, dan jika terjadi error, respons berbentuk {"error": "kode"} dikembalikan bersama kode status.

Langkah 3. Pilih spesifikasi, lokasi, dan image

Semua nilai yang dipakai saat membuat server berasal dari katalog. GET /catalog mengembalikan spesifikasi (plans), lokasi (locations), image (images), dan opsi tambahan (addons) yang dijual sekaligus. Jika ada jq, lebih mudah memilih bagian yang diperlukan saja.

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'

• Kode spesifikasi: seperti s1 dan s2, menunjukkan jenis dan ukuran. type berisi basic (SSD standar), fast (NVMe performa tinggi), cpu (CPU dedicated), atau mem (memori besar). monthly adalah tarif bulanan dalam dolar AS.
• Kode lokasi: nama kota seperti frankfurt, singapore, dan seoul.
• Kode image: sistem operasi seperti ubuntu-24-04, debian-13, dan almalinux-10, serta aplikasi seperti app-docker dan app-wordpress.
• Opsi tambahan: persentase backup otomatis, ukuran dan tarif per GB disk tambahan, serta tarif perlindungan DDoS. Opsi yang tidak dijual dikirim sebagai null.

Jika belum ada, instal jq dengan apt install -y jq di Ubuntu atau brew install jq di Mac. Daftarnya sama dengan yang dipilih di layar, jadi lebih mudah dilihat bersama perbedaan per spesifikasi di halaman harga.

Langkah 4. Membuat server

Kirim paket, lokasi, image, dan nama sebagai JSON ke POST /servers. Bayar untuk periode pertama paket yang dipilih dan pembuatan server dimulai.

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"}'

Jika berhasil, info server dikembalikan bersama kode status 201. id adalah kode server berbentuk S-XXXX-XXXX-XXXX, dan kode ini dipakai di semua permintaan berikutnya. root_password hanya ada sekali di respons ini, jadi langsung simpan. Password juga bisa dilihat di halaman server selama 7 hari.

• label: nama server. Gunakan huruf Latin, angka, titik, dan tanda hubung hingga 40 karakter, dan karakter lain diganti tanda hubung.
• backups: jika true, backup otomatis aktif.
• extra_disk_gb: ukuran disk blok NVMe tambahan. Masukkan salah satu nilai sizes_gb di katalog (50, 100, 250, 500, 1000).
• ddos_protection: jika true, perlindungan DDoS aktif.

Biaya opsi digabung dengan tarif bulanan server dan ditampilkan di monthly pada respons, lalu diperpanjang otomatis dengan nominal yang sama setiap tanggal tagihan. Setiap akun bisa membuat hingga 10 server.

Langkah 5. Cek status dan login

Server baru dimulai dengan status creating, menjadi running setelah siap, dan alamat ipv4 terisi. Loop di bawah memeriksa status setiap 10 detik dan menampilkan IP saat sudah running. Ganti kode server dengan kode server Anda.

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

Statusnya adalah salah satu dari creating, running, stopped, rebooting, installing, suspended, atau check. suspended berarti server dijeda karena tidak diperpanjang pada tanggal tagihan, dan check berarti kami sedang memeriksa hasil penyiapan server. Setelah IP muncul, hubungkan dengan ssh root@IP. Cara menghubungkan ada di panduan login pertama.

Langkah 6. Daya, perpanjangan, penghapusan

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: menyalakan server yang berhenti (stopped).
• stop, reboot: mematikan atau me-restart server yang berjalan (running).
• renew: membayar untuk 1, 3, 6, atau 12 bulan lagi sekarang. Server yang dijeda juga akan kembali aktif dengan permintaan ini.
• DELETE: menghapus server dan disknya lalu mengembalikan {"state": "deleted"}. Sisa masa bulan yang sudah dibayar tidak dikembalikan.

Jika mengirim tindakan yang tidak bisa dilakukan pada status saat ini, 409 wrong_state dikembalikan. Misalnya saat mengirim start ke server yang sudah menyala. Instal ulang dan pembuatan password root baru dilakukan di halaman server. Urutannya ada di panduan instal ulang.

Menjalankan urutan yang sama dengan Python

Alur yang sama jika ditulis sebagai skrip Python akan terlihat seperti ini. Memakai library requests (pip install requests).

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)

Kode error yang sering muncul

• 401 unauthorized: key tidak ada atau salah. Periksa apakah header berbentuk Authorization: Bearer hvp_....
• 403 not_allowed: terbuka setelah pembayaran pertama dikonfirmasi.
• 400 bad_request: nama atau nilai field salah. Pakai kode persis sesuai nilai katalog.
• 402 not_enough_balance: jumlah pembayaran di bawah $25. Kirim lagi dengan minimal $25.
• 409 limit: jumlah server yang bisa dibuat di akun sudah tercapai.
• 409 not_created: server tidak dapat dibuat, dan biaya kembali ke kredit akun Anda.
• 202 checking: kami sedang memeriksa hasil penyiapan server. Jangan kirim permintaan yang sama lagi; periksa daftar server Anda. Server akan diselesaikan atau biaya dikembalikan ke kredit akun Anda.
• 404 not_found: kode server atau alamat yang tidak ada di akun Anda.
• 409 wrong_state: tindakan yang tidak bisa dilakukan pada status saat ini.
• 429 rate_limited: batas permintaan per menit tercapai. Tunggu sebentar lalu kirim lagi.

Semua endpoint, field respons, dan contoh dikumpulkan di dokumentasi API. Hal yang bisa dilakukan dengan API dan kegunaannya bisa dilihat di halaman VPS API.