Gestionează-ți VPS-ul cu API-ul REST și curl: stare, alimentare, reinstalare, reînnoire

Comanda unui server prin API înseamnă o singură cerere. Asta e descris în Comandă un VPS în 4 apeluri API. Pagina de față e despre tot ce urmează: acțiunile de rutină pe care altfel le-ai face cu clicuri în panou, scrise ca comenzi curl pe care le poți lipi într-un script.

Fiecare comandă de mai jos a fost rulată pe API-ul nostru înainte de publicare, iar răspunsurile sunt copii scurtate a ceea ce s-a întors.

Pregătire

Două variabile țin comenzile scurte:

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

Tokenul vine din POST /auth/register sau din Settings → API tokens din panou. Ține-l în afara istoricului shell dacă și alții folosesc mașina; să-l citești dintr-un fișier cu export EQVPS_TOKEN=$(cat ~/.eqvps_token) e suficient.

Găsește-ți serverele

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

Fiecare intrare are un id de forma 47HZ7YF. Acesta e codul serviciului pe care îl primesc toate celelalte apeluri. Apoi imaginea completă a unui server:

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

access îți spune cum te conectezi. Pe un plan cu IPv4 propriu portul e 22; pe un plan NAT e portul tău redirecționat personal. Apelul doar citește, deci e sigur să-l interoghezi într-o buclă.

Dacă ai comandat fără cheie SSH, parola root e afișată o singură dată:

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

Cât timp serverul încă pornește, răspunsul spune password_pending și afișarea unică nu se consumă. Așteaptă o jumătate de minut și întreabă din nou.

Alimentare: start, stop, reboot

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

action este start, stop sau reboot. Un server care încă nu e activ (încă se creează sau e suspendat pentru neplată) răspunde 409 Service is not active. Nu e o eroare a scriptului tău. Verifică întâi status.

Metrici

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

CPU, memorie, rețea și disc ca serie temporală. timeframe este hour (implicit), day, week sau month. Bun pentru un cron care te anunță când discul tot crește. Contoarele de trafic pentru perioada de facturare curentă sunt în Verifică viteza și traficul.

Redenumește serverul

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

Noul nume e aplicat în sistemul care rulează de agentul guest, fără repornire pe Linux. Dacă serverul e oprit sau ai eliminat qemu-guest-agent, apelul întoarce 409 agent_unavailable și nimic nu se schimbă.

Reinstalează sistemul

Asta șterge discul. API-ul te obligă să scrii hostname-ul curent al serverului în confirm, astfel încât un script cu id de serviciu greșit să nu poată șterge mașina greșită:

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id vine din lista available_os a planului tău din GET /products sau din detaliile serverului însuși. Reinstalarea rulează în fundal; interoghează GET /services/{id} până când status redevine active.

Reînnoire și sold

Serverele se reînnoiesc lunar din soldul preplătit. Ca să vezi cât costă perioade mai lungi pentru acest server:

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

Ca să plătești în avans, să zicem trei luni, într-un singur apel:

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

months este 1, 3, 6 sau 12, iar 12 se facturează la prețul anual cu reducerea lui. Răspunsul spune paid_from_balance: true și dă noua dată de expirare. Dacă soldul nu acoperă suma, nu se încasează nimic: primești paid_from_balance: false și în schimb un checkout_url pentru acea factură. După ce soldul a fost alimentat, POST $API/invoices/{invoice_id}/pay plătește factura din sold; dacă tot nu ajunge, întoarce același tip de checkout_url și nu încasează nimic. Verificarea și alimentarea soldului:

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

Răspunsul la alimentare conține un checkout_url. E o plată crypto: USDT, USDC sau ETH pe Base, Ethereum sau Polygon. Soldul e creditat după ce plata se confirmă on-chain. Plata e singurul pas pe care un script nu-l poate face în locul tău, decât dacă deține un portofel.

Merge și Monero, dar doar ca alimentare de sold cu verificare manuală: trimiți XMR, transmiți id-ul tranzacției și credităm după verificare. Vezi Plătește cu Monero.

Anulează, și răzgândește-te

Anularea sigură lasă serverul să ruleze până la sfârșitul perioadei plătite și pur și simplu nu-l reînnoiește:

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason e obligatoriu. Câteva cuvinte ajung. Te-ai răzgândit înainte de dată?

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

Există și "type": "immediate". Șterge serverul și datele lui imediat, cere "confirm": "<hostname>" și nu poate fi anulat. Dacă nu vrei cu adevărat asta, folosește end_of_period.

Ține tokenul în viață

Tokenurile noi trăiesc un an implicit. Fiecare răspuns autentificat are antetul X-Token-Expires-At, ca un script să observe din timp. Schimbă tokenul cu unul nou:

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

Tokenul vechi nu mai funcționează imediat, așa că salvează-l pe cel nou înainte să faci orice altceva.

Erori care merită tratate

Faci asta dintr-un client AI în loc de un script? Aceleași acțiuni există ca unelte MCP — vezi Cum își administrează un agent propriul VPS prin MCP și referința API. Nu ai încă un server? Alege un plan.