Create Server

POST /api/servers

Create Server

cURL

curl --request POST \
  --url https://api.example.com/api/servers \
  --header 'Content-Type: application/json' \
  --data '
{
  "uuid": "<string>",
  "start_on_completion": true
}
'

import requests

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

payload = {
    "uuid": "<string>",
    "start_on_completion": True
}
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({uuid: '<string>', start_on_completion: true})
};

fetch('https://api.example.com/api/servers', 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",
  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([
    'uuid' => '<string>',
    'start_on_completion' => true
  ]),
  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"

	payload := strings.NewReader("{\n  \"uuid\": \"<string>\",\n  \"start_on_completion\": true\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")
  .header("Content-Type", "application/json")
  .body("{\n  \"uuid\": \"<string>\",\n  \"start_on_completion\": true\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"uuid\": \"<string>\",\n  \"start_on_completion\": true\n}"

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

Creates a new server on the Wings instance and begins the installation process.

Authentication

Requires the Wings authentication token in the Authorization header:

Authorization: Bearer <token>

Request Body

uuid · string · required

The UUID of the server to create. Must be a valid UUIDv4 format.

start_on_completion · boolean · default: false

Whether to automatically start the server after installation completes.

Response

Returns 202 Accepted to indicate the server creation and installation process has started in the background.

Error Responses

422 Unprocessable Entity

The data provided could not be validated (e.g., invalid UUID format).

500 Internal Server Error

An error occurred while creating the server instance.

Behavior

This endpoint:

1. Validates the provided UUID format
2. Fetches server configuration from the Panel
3. Initializes the server instance in Wings
4. Adds the server to the manager
5. Begins installation in background:
   • Creates the server environment (Docker container)
   • Runs the installation process
   • Optionally starts the server if start_on_completion is true

Installation runs asynchronously, so errors during installation will be logged but not returned in the API response.

Example Request

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

Example Response

HTTP/1.1 202 Accepted

Notes

• The server configuration is fetched from the Panel using the provided UUID
• Installation happens asynchronously in the background
• Monitor server logs or websocket events to track installation progress
• If installation fails, the server will remain in an installing state until manually triggered again

Source Reference

Implemented in router/router_system.go:61