VPS API hızlı başlangıç: API anahtarı oluşturma ve ilk sunucuyu oluşturma

2. adım. Kimlik doğrulama ve ilk istek

Tüm istekleri https://helpervps.com/api/v1 temel adresinin altına gönderin ve Authorization: Bearer anahtar başlığını ekleyin. İlk istek olarak sunucu listenizi alın. Sunucu yoksa boş bir liste [] döner.

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

Her hesap dakikada 300 isteğe kadar gönderebilir, sunucu oluşturma ise 10 dakikada 10 istekle sınırlıdır. Durumu kontrol eden tekrarlı isteklerde birkaç saniye aralık bırakmanız yeterlidir. Yanıtların hepsi JSON'dur; hata oluştuğunda durum koduyla birlikte {"error": "code"} biçiminde döner.

3. adım. Plan, bölge ve imaj seçin

Sunucu oluştururken girilen değerlerin hepsi katalogdan gelir. GET /catalog, satıştaki planları (plans), bölgeleri (locations), imajları (images) ve ek seçenekleri (addons) tek seferde döndürür. jq varsa yalnızca gereken kısımları seçerek görmek kolaydır.

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 kodu: s1, s2 gibi türü ve boyutu gösterir. type değeri basic (SSD Standart), fast (NVMe Yüksek Performans), cpu (Dedicated CPU) veya mem (Yüksek Bellek) olur. monthly, ABD doları cinsinden aylık ücrettir.
• Bölge kodu: frankfurt, singapore, seoul gibi şehir adlarıdır.
• İmaj kodu: ubuntu-24-04, debian-13, almalinux-10 gibi işletim sistemleri ve app-docker, app-wordpress gibi uygulamalardır.
• Ek seçenekler: otomatik yedekleme oranı, ek disk boyutları ve GB başına ücret ile DDoS koruması ücretidir. Satışta olmayan seçenekler null olarak gelir.

jq yoksa Ubuntu'da apt install -y jq, Mac'te brew install jq ile kurun. Ekranda seçtiğiniz listeyle aynı olduğu için planlar arasındaki farkları fiyatlar sayfasıyla birlikte incelemek pratiktir.

4. adım. Sunucu oluşturun

Planı, konumu, imajı ve adı JSON olarak POST /servers adresine gönderin. Seçtiğiniz planın ilk dönemi için ödeme yapın ve sunucu oluşturma başlar.

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

Başarılı olursa 201 durum koduyla birlikte sunucu bilgileri döner. id, S-XXXX-XXXX-XXXX biçiminde bir sunucu kodudur ve sonraki tüm isteklerde bu kodu kullanırsınız. root_password bu yanıtta bir kez yer aldığı için hemen kaydedin. Sunucu sayfasında da 7 gün boyunca görebilirsiniz.

• label: sunucu adıdır. Harf, rakam, nokta ve tire ile 40 karaktere kadar yazılır, diğer karakterler tireye dönüştürülür.
• backups: true ise otomatik yedekleme açılır.
• extra_disk_gb: ek NVMe blok disk boyutudur. Katalogdaki sizes_gb değerlerinden (50, 100, 250, 500, 1000) birini girin.
• ddos_protection: true ise DDoS koruması açılır.

Seçenek ücretleri sunucunun aylık ücretine eklenerek yanıttaki monthly alanında gösterilir ve her ödeme tarihinde aynı tutarla otomatik yenilenir. Her hesapta 10 sunucuya kadar oluşturabilirsiniz.

5. adım. Durum kontrolü ve bağlantı

Yeni sunucu creating durumunda başlar, hazır olduğunda running olur ve ipv4 adresi dolar. Aşağıdaki döngü her 10 saniyede bir durumu kontrol eder ve running olduğunda IP'yi gösterir. Sunucu kodunu kendi sunucunuzun koduyla değiştirin.

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

Durum, creating, running, stopped, rebooting, installing, suspended veya check değerlerinden biridir. suspended, sunucunun fatura tarihinde yenilenmediği için duraklatıldığını; check ise sunucu kurulum sonucunun kontrol edildiğini ifade eder. IP göründüğünde ssh root@IP ile bağlanın. Bağlantı yöntemi ilk giriş rehberinde yer alır.

6. adım. Güç, yenileme ve silme

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: durdurulmuş (stopped) bir sunucuyu açar.
• stop, reboot: çalışan (running) bir sunucuyu kapatır veya yeniden başlatır.
• renew: şimdi 1, 3, 6 veya 12 ay daha öder. Askıya alınmış bir sunucu da bu istekle yeniden etkinleşir.
• DELETE: sunucuyu ve diski siler, {"state": "deleted"} döndürür. Ödemesi yapılmış ayın kalan süresi iade edilmez.

Mevcut durumda yapılamayan bir işlem gönderirseniz 409 wrong_state döner. Örneğin zaten açık bir sunucuya start gönderdiğinizde bu olur. Yeniden kurulum ve yeni root parolası oluşturma işlemlerini sunucu sayfasından yaparsınız. Adımlar yeniden kurulum rehberinde yer alır.

Aynı adımları Python ile çalıştırma

Aynı akışı bir Python betiğiyle yazarsanız şöyle olur. requests kütüphanesini (pip install requests) kullanır.

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)

Sık görülen hata kodları

• 401 unauthorized: anahtar yok veya hatalı. Başlığın Authorization: Bearer hvp_... biçiminde olduğunu kontrol edin.
• 403 not_allowed: ilk ödemeniz onaylandığında açılır.
• 400 bad_request: alan adı veya değeri hatalı. Kodları katalogdaki değerlerle aynen kullanın.
• 402 not_enough_balance: ödeme tutarı $25'in altında. En az $25 ile tekrar gönderin.
• 409 limit: hesabınızda oluşturabileceğiniz sunucu sayısına ulaştınız.
• 409 not_created: sunucu oluşturulamadı ve ücret hesap bakiyenize iade edilir.
• 202 checking: sunucu kurulum sonucunu kontrol ediyoruz. Aynı isteği tekrar göndermeyin; sunucu listenizi kontrol edin. Sunucu tamamlanır veya ücret hesap bakiyenize iade edilir.
• 404 not_found: hesabınızda olmayan bir sunucu kodu veya adres.
• 409 wrong_state: mevcut durumda yapılamayan bir işlem.
• 429 rate_limited: dakikalık istek sınırına ulaştınız. Biraz bekleyip yeniden gönderin.

Tüm uç noktaları, yanıt alanlarını ve örnekleri API belgelerinde topladık. API ile yapabileceklerinizi ve kullanım alanlarını VPS API sayfasında görebilirsiniz.