Restart a VPS and wait until it is back

A restart shuts the VPS down through its operating system and starts it again. The API answers at once with a job. You follow the job until it finishes, then check that the server is running.

Doing this often? Let an AI app do it

Connect Hostup's MCP server to Claude, ChatGPT or Codex and say what you want done, for example:

Restart every VPS whose name starts with web- and tell me when they are all back

Connect an AI app

Before you start

• The requests use $HOSTUP_API_KEY, the key from the Quickstart. Add power:vm to it: open the key’s menu in API Management, click Edit Permissions and tick the scope.
• jq, which the wait script in step 3 uses.
• The ID of the VPS, vps_…. If you came from the Quickstart, $VPS_ID holds it already. Otherwise take it from List VPS instances and set it:

export VPS_ID="vps_…"   # your VPS: List VPS instances

Steps

1. Check that the VPS can restart

Read the details of the VPS with GET /api/v2/vps/{id}/details. It is the same call as step 4 of the Quickstart.

GET /api/v2/vps/{id}/details

curl "https://cloud.hostup.se/api/v2/vps/$VPS_ID/details" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

Response 200

{
  "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "powerState": "running",
  "bandwidth": { "hasOverage": false, "…": "…" },
  "actions": {
    "canRestart": { "allowed": true, "reason": null },
    "…": "…"
  },
  "…": "…"
}

Restart when actions.canRestart.allowed is true and bandwidth.hasOverage is false. canRestart needs a VPS that is active and running. It does not look at the bandwidth allowance.

If allowed is false

reason says why, for example “VPS is stopped. Start it instead of restarting.” Use Start a VPS for a stopped server.

If hasOverage is true

The VPS has used up its bandwidth allowance. The restart would answer 403. Add bandwidth with Change VPS resources first.

2. Restart it

POST /api/v2/vps/{id}/actions/restart takes no body. The Content-Type header is still needed. Without it the API answers 415.

Caution

The VPS is offline until it has started again. If the operating system has not shut down after 60 seconds, the power is cut, as if the plug were pulled. Check that $VPS_ID is the server you mean.

POST /api/v2/vps/{id}/actions/restart

curl -X POST "https://cloud.hostup.se/api/v2/vps/$VPS_ID/actions/restart" \
  -H "Authorization: Bearer $HOSTUP_API_KEY" \
  -H "Content-Type: application/json"

Response 202

{
  "operation": {
    "status": "queued",
    "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
    "pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3"
  }
}

Keep operation.jobId from your response. Step 3 uses it.

export JOB_ID="job_…"   # operation.jobId above

If you don’t want to wait for the shutdown

Send {"force": true} as the body. The power is cut at once and the VPS starts again. Hard reboot a VPS does the same.

3. Wait for the job to finish

GET /api/jobs/{jobId} shows where the job is. The job endpoint is older than v2. Its answer has the job inside data.

GET /api/jobs/{jobId}

curl "https://cloud.hostup.se/api/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
    "status": "completed",
    "progressText": "Operation completed successfully",
    "…": "…"
  },
  "…": "…"
}

To wait until it ends, run wait-for-job.sh. It polls every 4 seconds and stops on completed or failed.

./wait-for-job.sh "/api/jobs/$JOB_ID"

If the job failed

data.error only says Job failed. data.progressText says what went wrong, for example that the server did not respond to a shutdown. The shutdown may already have happened. Step 4 shows the power state. When powerState is stopped, start the VPS with Start a VPS. Wait for its job the same way.

4. Check that the server is running

A completed job means the VPS was shut down and started again. GET /api/v2/vps/{id}/status shows what the server is doing now.

GET /api/v2/vps/{id}/status

curl "https://cloud.hostup.se/api/v2/vps/$VPS_ID/status" \
  -H "Authorization: Bearer $HOSTUP_API_KEY"

Response 200

{
  "id": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "powerState": "running",
  "uptimeSeconds": 42,
  "…": "…"
}

A small uptimeSeconds confirms the reboot. Your own services on the server may need a little longer to come up than the server itself.

What happens next

If a restart of this VPS is already running, you get that job back instead of a second restart. That holds with or without force. A restart creates no invoice.

Restart e-mails for this VPS stay off for 15 minutes after the call. Your own restart does not send one. These e-mails are turned on or off in the client area.

Errors you may hit

• 404 vps_not_found: no VPS on your account has that ID. Check that VPS_ID holds your VPS ID, not the placeholder.
• 401 unauthorized or 403 forbidden with requiredScopes: the key was refused. When a key is refused has every case.
• 403 forbidden without requiredScopes: detail only says You do not have permission to access this resource. The VPS is not active. Or its bandwidth allowance is used up (step 1 shows both). Or another operation runs on it: a backup, a restore, a snapshot rollback, a start or a stop. pendingTasks in Get the live status of a VPS lists those. Wait until they finish and try again.
• 403 payg_payment_overdue: a Cloud VPS on an account with an overdue invoice. Pay the invoice, then restart.
• While the VPS is still being set up: 400 invalid_request, 403 forbidden or 409 upstream_failed. Wait until setup finishes.
• 400 invalid_request: the body has an unknown field. It also comes when force is not true or false. The string "true" is refused. A body that is not valid JSON gets 400 as well.

Related endpoints

• Get VPS details and action gates
• Restart a VPS
• Hard reboot a VPS
• Start a VPS
• Get the status of a job
• Get the live status of a VPS

Next: Jobs. Every action that takes time answers with a job like this one.