Server Power Action

POST /api/servers/:server/power

Server Power Action

cURL

curl --request POST \
  --url https://api.example.com/api/servers/:server/power \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "<string>",
  "wait_seconds": 123
}
'

import requests

url = "https://api.example.com/api/servers/:server/power"

payload = {
    "action": "<string>",
    "wait_seconds": 123
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({action: '<string>', wait_seconds: 123})
};

fetch('https://api.example.com/api/servers/:server/power', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/servers/:server/power",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'action' => '<string>',
    'wait_seconds' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/servers/:server/power"

	payload := strings.NewReader("{\n  \"action\": \"<string>\",\n  \"wait_seconds\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/servers/:server/power")
  .header("Content-Type", "application/json")
  .body("{\n  \"action\": \"<string>\",\n  \"wait_seconds\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/servers/:server/power")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"action\": \"<string>\",\n  \"wait_seconds\": 123\n}"

response = http.request(request)
puts response.read_body

Controls the power state of a server. This endpoint triggers power actions asynchronously and returns immediately.

Authentication

Requires the Wings authentication token in the Authorization header:

Authorization: Bearer <token>

Path Parameters

server · string · required

The UUID of the server

Request Body

action · string · required

The power action to perform. Must be one of:

• start - Start the server
• stop - Stop the server gracefully
• restart - Restart the server
• kill - Forcefully terminate the server (SIGKILL)

wait_seconds · integer · default: 30

Number of seconds to wait for a lock on the power action (0-300). Defaults to 30 if not provided or out of range.

Response

Returns 202 Accepted when the power action has been queued for processing.

Error Responses

400 Bad Request

Cannot start or restart a suspended server.

404 Not Found

The requested server does not exist on this Wings instance.

422 Unprocessable Entity

The power action provided was not valid.

Behavior

Power Action Locking

• All actions except kill acquire an exclusive lock to prevent concurrent power actions
• wait_seconds controls how long to wait for the lock (default: 30 seconds)
• kill action attempts to acquire lock but proceeds even if it fails

Action Details

start

• Only works if server state is offline
• Runs pre-boot checks (sync, disk space, permissions)
• Suspended servers are blocked

stop

• Waits up to 10 minutes for graceful shutdown
• Uses terminate signal if graceful shutdown fails

restart

• Combines stop + start
• Waits for complete shutdown before starting
• Suspended servers are blocked

kill

• Sends SIGKILL to immediately terminate the process
• Does not wait for locks (bypasses lock contention)
• Use for stuck or unresponsive servers

Pre-boot Process (start/restart)

1. Syncs server configuration with Panel
2. Checks suspension status
3. Syncs environment variables and resource limits
4. Verifies disk space availability
5. Updates configuration files
6. Sets file permissions (if enabled in config)

Example Requests

Start Server

curl -X POST https://wings.example.com/api/servers/8d3f9a2e-5c7b-4f1e-9d2a-6e8f1c3b5a7d/power \
  -H "Authorization: Bearer your-wings-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "start"
  }'

Restart Server with Custom Wait Time

curl -X POST https://wings.example.com/api/servers/8d3f9a2e-5c7b-4f1e-9d2a-6e8f1c3b5a7d/power \
  -H "Authorization: Bearer your-wings-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "restart",
    "wait_seconds": 60
  }'

Kill Server

curl -X POST https://wings.example.com/api/servers/8d3f9a2e-5c7b-4f1e-9d2a-6e8f1c3b5a7d/power \
  -H "Authorization: Bearer your-wings-token" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "kill"
  }'

Example Response

HTTP/1.1 202 Accepted

Notes

• Power actions run asynchronously in the background
• Use websockets to monitor actual state changes
• Errors during async execution are logged but not returned to the API caller
• Multiple power actions are serialized via exclusive locking
• The kill action bypasses most safety checks and should be used sparingly

Source Reference

Implemented in router/router_server.go:53 and server/power.go:56