REST API と curl で VPS を管理する：状態、電源、再インストール、更新

API でのサーバー注文はリクエスト 1 回で済みます。その方法は API 呼び出し 4 回で VPS を注文する にあります。このページはその後のすべてについてです。普段ダッシュボードでクリックしている定型作業を、スクリプトに貼り付けられる curl コマンドとしてまとめました。

以下のコマンドはすべて公開前に当社 API に対して実行し、レスポンスは返ってきた内容を短くしたものです。

準備

変数 2 つでコマンドを短く保ちます。

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

トークンは POST /auth/register か、ダッシュボードの Settings → API tokens から取得します。他の人もそのマシンを使うならシェル履歴に残さないでください。export EQVPS_TOKEN=$(cat ~/.eqvps_token) でファイルから読み込めば十分です。

サーバーを探す

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

各エントリには 47HZ7YF のような id があります。これが他のすべての呼び出しで使うサービスコードです。次に 1 台のサーバーの全体像です。

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 にはログイン方法が示されます。専用 IPv4 付きのプランではポートは 22、NAT プランではあなた専用の転送ポートです。この呼び出しは読み取り専用なので、ループで確認しても安全です。

SSH キーなしで注文した場合、root パスワードは一度だけ表示されます。

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

サーバーがまだ起動中の間は password_pending が返り、一度きりの表示は消費されません。30 秒ほど待ってから再度問い合わせてください。

電源：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 は start、stop、reboot のいずれかです。まだ有効でないサーバー（作成中、または未払いで停止中）は 409 Service is not active を返します。スクリプトのエラーではありません。先に status を確認してください。

メトリクス

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

CPU、メモリ、ネットワーク、ディスクの時系列データです。timeframe は hour（既定）、day、week、month です。ディスクが増え続けたときに通知する cron ジョブに便利です。現在の請求期間のトラフィックカウンターは 速度とトラフィックを確認する にあります。

サーバー名を変更する

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

新しい名前はゲストエージェントによって稼働中のシステム内に適用され、Linux では再起動は不要です。サーバーが停止している場合や qemu-guest-agent を削除した場合、呼び出しは 409 agent_unavailable を返し、何も変わりません。

OS を再インストールする

これはディスクを消去します。API では confirm にサーバーの現在のホスト名を入力する必要があるため、サービス ID を間違えたスクリプトが別のマシンを消すことはありません。

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 は GET /products にあるプランの available_os 一覧か、サーバー自体の詳細から取得します。再インストールはバックグラウンドで進むので、status が再び active になるまで GET /services/{id} を確認してください。

更新と残高

サーバーはプリペイド残高から毎月更新されます。このサーバーで長い期間がいくらになるかを見るには：

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

たとえば 3 か月分を 1 回の呼び出しで前払いするには：

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

months は 1、3、6、12 のいずれかで、12 は割引付きの年額で請求されます。レスポンスには paid_from_balance: true と新しい有効期限が含まれます。残高が金額に満たない場合は何も請求されず、paid_from_balance: false とその請求書の checkout_url が返ります。残高をチャージしたら、POST $API/invoices/{invoice_id}/pay でその請求書を残高から支払えます。まだ足りなければ同じ種類の checkout_url が返り、何も請求されません。残高の確認とチャージ：

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

チャージのレスポンスには checkout_url が含まれます。これは暗号資産の決済で、Base、Ethereum、Polygon 上の USDT、USDC、ETH を使います。支払いがオンチェーンで承認されると残高に反映されます。支払いは、ウォレットを持たない限りスクリプトが代わりにできない唯一の手順です。

Monero も使えますが、手動確認付きの残高チャージに限ります。XMR を送金してトランザクション ID を提出すると、確認後に反映します。Monero で支払う をご覧ください。

解約と取り消し

安全な解約では、支払い済み期間の終わりまでサーバーは稼働を続け、単に更新されなくなります。

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 は必須です。数語で構いません。期日前に気が変わったら：

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

"type": "immediate" もあります。サーバーとデータを即座に削除し、"confirm": "<hostname>" が必要で、取り消しはできません。本当にそのつもりでない限り、end_of_period を使ってください。

トークンを有効に保つ

新しいトークンの寿命は既定で 1 年です。認証済みのレスポンスにはすべて X-Token-Expires-At ヘッダーが付くので、スクリプトは早めに気付けます。トークンを新しいものに交換するには：

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

古いトークンはすぐに使えなくなるので、他の操作の前に新しいトークンを保存してください。

処理しておきたいエラー

スクリプトではなく AI クライアントから行いますか？ 同じ操作が MCP ツールとして用意されています。AI エージェントが MCP で自分の VPS を管理する方法 と API リファレンス をご覧ください。まだサーバーがなければ、プランを選ぶ からどうぞ。