Managing instances

Once an instance exists you can drive its full lifecycle through the API. All management endpoints operate on your instances only — an ID you do not own returns 404.

Read operations require vps:read; mutating operations require vps:write (implied by vps:create).

Inspect

# All your instances
curl .../api/v1/instances -H "Authorization: Bearer $KEY"

# One instance
curl .../api/v1/instances/123 -H "Authorization: Bearer $KEY"

# Live status + usage
curl .../api/v1/instances/123/status -H "Authorization: Bearer $KEY"

# Historical metrics (range = 1h|6h|24h|7d|30d)
curl ".../api/v1/instances/123/metrics?range=24h" -H "Authorization: Bearer $KEY"

Power & OS

curl -X POST .../api/v1/instances/123/start   -H "Authorization: Bearer $KEY"
curl -X POST .../api/v1/instances/123/stop    -H "Authorization: Bearer $KEY"
curl -X POST .../api/v1/instances/123/restart -H "Authorization: Bearer $KEY"

# Reinstall the OS (os slugs come from GET /services/{plan_id}/os-options)
# An ssh_pubkey is installed for root on the fresh system. Keys are not carried
# over from the previous installation, so pass it on every reinstall. Reusing one
# key across instances is fine, and a reinstall that cannot install the key fails
# instead of returning a server you cannot log into.
curl -X POST .../api/v1/instances/123/reinstall \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"os": "debian-12", "ssh_pubkey": "ssh-ed25519 AAAA..."}'

# Reset the root password (returned once, never stored)
curl -X POST .../api/v1/instances/123/reset-password -H "Authorization: Bearer $KEY"

The reset-password response carries the new password. It is not retrievable afterwards, so store it on receipt — a copy is also emailed to the account owner.

{ "ok": true, "action": "reset_password", "provider_id": "754",
  "password": "…", "show_once": true }

Networking

# Change hostname
curl -X PATCH .../api/v1/instances/123/hostname \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"hostname": "db-01.example.com"}'

# Set reverse DNS (PTR)
curl -X POST .../api/v1/instances/123/rdns \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.10", "ptr": "db-01.example.com"}'

Scaling (resize)

List plans you can move to (same data centre), then resize. Upgrades are prorated and charged to your wallet; downgrades take effect with no refund.

curl .../api/v1/instances/123/available-plans -H "Authorization: Bearer $KEY"

curl -X POST .../api/v1/instances/123/resize \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"service_id": 15}'

Snapshots & backups

# Snapshots
curl .../api/v1/instances/123/snapshots -H "Authorization: Bearer $KEY"
curl -X POST .../api/v1/instances/123/snapshots \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "before-upgrade"}'
curl -X POST .../api/v1/instances/123/snapshots/9/restore -H "Authorization: Bearer $KEY"
curl -X DELETE .../api/v1/instances/123/snapshots/9       -H "Authorization: Bearer $KEY"

# Backups
curl .../api/v1/instances/123/backups -H "Authorization: Bearer $KEY"
curl -X POST .../api/v1/instances/123/backups/4/restore -H "Authorization: Bearer $KEY"

Boot media & rescue

# ISO library
curl .../api/v1/instances/123/isos -H "Authorization: Bearer $KEY"
curl -X POST .../api/v1/instances/123/iso \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"iso_id": 7}'
curl -X DELETE .../api/v1/instances/123/iso -H "Authorization: Bearer $KEY"

# Rescue mode — enter (boots the rescue ISO) and exit (boots from disk)
curl -X POST   .../api/v1/instances/123/rescue -H "Authorization: Bearer $KEY"
curl -X DELETE .../api/v1/instances/123/rescue -H "Authorization: Bearer $KEY"

Both calls switch the boot mode and then restart the instance so it takes effect. If restarted comes back false the mode was set but the reboot was refused (usually another provider task was still running) — reboot the instance yourself to apply it.

{ "ok": true, "action": "rescue_enter", "boot_mode": "rescue", "restarted": true }

The rescue environment has no SSH credentials of its own — reach it through the VNC console on the instance page in the panel. Your disk is left unmounted, so mount it from inside rescue to repair it.

Activity

curl ".../api/v1/instances/123/tasks?limit=20&offset=0" -H "Authorization: Bearer $KEY"

For exact request/response shapes of every endpoint, see the API Reference.