Je VPS beheren met de REST-API en curl: status, aan/uit, herinstallatie, verlenging

Een server bestellen via de API kost één verzoek. Dat staat in Een VPS bestellen in 4 API-aanroepen. Deze pagina gaat over alles daarna: de routineacties die je anders in het dashboard zou aanklikken, geschreven als curl-commando's om in een script te plakken.

Elk commando hieronder hebben we vóór publicatie tegen onze API uitgevoerd, en de antwoorden zijn ingekorte kopieën van wat terugkwam.

Voorbereiding

Twee variabelen houden de commando's kort:

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

Het token komt uit POST /auth/register of uit Settings → API tokens in het dashboard. Houd het buiten je shellgeschiedenis als anderen de machine gebruiken; het uit een bestand lezen met export EQVPS_TOKEN=$(cat ~/.eqvps_token) is genoeg.

Je servers vinden

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

Elk item heeft een id zoals 47HZ7YF. Dat is de servicecode die elke andere aanroep verwacht. Dan het volledige beeld van één 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 vertelt je hoe je inlogt. Bij een pakket met eigen IPv4 is de poort 22; bij een NAT-pakket is het je persoonlijke doorgestuurde poort. Deze aanroep leest alleen, dus hem in een lus opvragen is veilig.

Heb je besteld zonder SSH-sleutel, dan wordt het root-wachtwoord één keer getoond:

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

Zolang de server nog opstart, zegt het antwoord password_pending en is de eenmalige weergave niet verbruikt. Wacht een halve minuut en vraag het opnieuw.

Aan/uit: 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 is start, stop of reboot. Een server die nog niet actief is (nog in aanmaak, of geschorst wegens niet-betaling) antwoordt 409 Service is not active. Dat is geen fout in je script. Controleer eerst status.

Metrics

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

CPU, geheugen, netwerk en schijf als tijdreeks. timeframe is hour (standaard), day, week of month. Handig voor een cronjob die je waarschuwt als de schijf blijft groeien. De verkeerstellers voor de huidige factuurperiode staan in Snelheid en verkeer controleren.

De server hernoemen

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

De nieuwe naam wordt door de guest agent in het draaiende systeem gezet, zonder herstart op Linux. Is de server gestopt, of heb je qemu-guest-agent verwijderd, dan geeft de aanroep 409 agent_unavailable en verandert er niets.

Het OS herinstalleren

Deze wist de schijf. De API laat je de huidige hostname van de server in confirm typen, zodat een script met het verkeerde service-id niet de verkeerde machine kan wissen:

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 komt uit de lijst available_os van je pakket in GET /products of uit de details van de server zelf. De herinstallatie draait op de achtergrond; vraag GET /services/{id} op tot status weer active is.

Verlenging en saldo

Servers verlengen elke maand uit je prepaid saldo. Om te zien wat langere termijnen voor deze server kosten:

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

Om vooruit te betalen, zeg drie maanden, in één aanroep:

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

months is 1, 3, 6 of 12, en 12 wordt gefactureerd tegen de jaarprijs met korting. Het antwoord zegt paid_from_balance: true en geeft de nieuwe vervaldatum. Dekt het saldo het bedrag niet, dan wordt niets afgeschreven: je krijgt paid_from_balance: false en in plaats daarvan een checkout_url voor die factuur. Zodra het saldo is aangevuld, betaalt POST $API/invoices/{invoice_id}/pay die factuur uit het saldo; is het nog steeds te weinig, dan komt dezelfde soort checkout_url terug en wordt niets afgeschreven. Saldo bekijken en aanvullen:

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

Het antwoord op de aanvulling bevat een checkout_url. Dat is een crypto-betaling: USDT, USDC of ETH op Base, Ethereum of Polygon. Het saldo wordt bijgeschreven zodra de betaling on-chain bevestigd is. Betalen is de enige stap die een script niet voor je kan doen, tenzij het een wallet heeft.

Monero werkt ook, maar alleen als saldo-aanvulling met handmatige controle: je stuurt XMR, geeft de transactie-id door, en wij schrijven het bij na verificatie. Zie Betalen met Monero.

Opzeggen, en van gedachten veranderen

De veilige manier van opzeggen laat de server draaien tot het einde van de betaalde periode en verlengt hem gewoon niet:

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 is verplicht. Een paar woorden is genoeg. Van gedachten veranderd vóór de datum?

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

"type": "immediate" bestaat ook. Dat verwijdert de server en zijn data meteen, vereist "confirm": "<hostname>" en kan niet worden teruggedraaid. Tenzij je het echt meent, gebruik end_of_period.

Het token in leven houden

Nieuwe tokens leven standaard een jaar. Elk geauthenticeerd antwoord draagt een header X-Token-Expires-At, zodat een script het op tijd kan merken. Ruil het token in voor een nieuw:

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

Het oude token werkt direct niet meer, dus sla het nieuwe op voordat je iets anders doet.

Fouten die je wilt afhandelen

Doe je dit liever vanuit een AI-client dan vanuit een script? Dezelfde acties bestaan als MCP-tools — zie Hoe een agent zijn eigen VPS via MCP beheert en de API-referentie. Nog geen server? Kies een pakket.