Manage your VPS with the REST API and curl: status, power, reinstall, renewal

Ordering a server through the API takes one request. That's covered in Order a VPS in 4 API calls. This page is about everything after it: the routine actions you'd otherwise click through in the dashboard, written as curl commands you can paste into a script.

Every command below was run against our API before publishing, and the responses are trimmed copies of what came back.

Setup

Two variables keep the commands short:

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

The token comes from POST /auth/register or from Settings → API tokens in the dashboard. Keep it out of shell history if other people use the machine; reading it from a file with export EQVPS_TOKEN=$(cat ~/.eqvps_token) is enough.

Find your servers

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

Each entry has an id like 47HZ7YF. That's the service code every other call takes. Then the full picture of one 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 tells you how to log in. On a plan with its own IPv4 the port is 22; on a NAT plan it's your personal forwarded port. This call is read-only, so polling it in a loop is safe.

If you ordered without an SSH key, the root password is shown once:

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

While the server is still booting, the answer says password_pending and the one-time reveal isn't used up. Wait half a minute and ask again.

Power: 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 or reboot. A server that isn't active yet (still being created, or suspended for non-payment) answers 409 Service is not active. That's not an error in your script. Check status first.

Metrics

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

CPU, memory, network and disk as a time series. timeframe is hour (default), day, week or month. Good for a cron job that pings you when the disk keeps growing. Traffic counters for the current billing period are in Check speed and traffic.

Rename the server

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

The new name is applied inside the running system by the guest agent, no reboot needed on Linux. If the server is stopped, or you removed qemu-guest-agent, the call returns 409 agent_unavailable and nothing changes.

Reinstall the OS

This one wipes the disk. The API makes you type the server's current hostname into confirm, so a script with the wrong service id can't erase the wrong machine:

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 comes from the available_os list of your plan in GET /products or in the server's own details. The reinstall runs in the background; poll GET /services/{id} until status is active again.

Renewal and the balance

Servers renew monthly from your prepaid balance. To see what longer terms cost for this server:

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

To pay ahead, say three months, in one call:

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 or 12, and 12 is billed at the annual price with its discount. The answer says paid_from_balance: true and gives the new expiry date. If the balance doesn't cover the amount, nothing is charged: you get paid_from_balance: false and a checkout_url for that invoice instead. Once the balance has been topped up, POST $API/invoices/{invoice_id}/pay pays that invoice from the balance; if the balance still falls short, it returns the same kind of checkout_url and charges nothing. Checking and topping up the balance:

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

The top-up answer contains a checkout_url. That's a crypto checkout: USDT, USDC or ETH on Base, Ethereum or Polygon. The balance is credited once the payment confirms on-chain. Paying is the one step a script can't do for you unless it holds a wallet.

Monero works too, but only as a balance top-up with a manual check: you send XMR, submit the transaction id, and we credit it after verifying. See Pay with Monero.

Cancel, and change your mind

The safe kind of cancel keeps the server running until the paid period ends and simply doesn't renew it:

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 required. A few words is fine. Changed your mind before the date?

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

"type": "immediate" exists too. It deletes the server and its data at once, needs "confirm": "<hostname>", and can't be undone. Unless you really mean it, use end_of_period.

Keep the token alive

New tokens live a year by default. Every authenticated response carries an X-Token-Expires-At header, so a script can notice it early. Swap the token for a fresh one:

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

The old token stops working immediately, so save the new one before you do anything else.

Errors worth handling

Doing this from an AI client instead of a script? The same actions exist as MCP tools — see How an agent runs its own VPS over MCP and the API reference. If you don't have a server yet, pick a plan.