Initiate Server Transfer

Start transferring a server to another node

POST /api/servers/:server/transfer

Initiates an outgoing server transfer to a destination node. This endpoint archives the server data and streams it to the target node.

The server must be offline before the transfer can begin. The transfer process will automatically stop the server if it’s running.

Path Parameters

server · string · required

The UUID of the server to transfer

Request Body

url · string · required

The destination node’s transfer endpoint URL where the archive will be sent

token · string · required

JWT bearer token for authenticating with the destination node

server · object · required

Server configuration details for the destination node

Show properties

uuid · string · required

The server’s UUID

start_on_completion · boolean

Whether to start the server after transfer completes (default: false)

Response

Returns 202 Accepted when the transfer is successfully initiated. The transfer runs asynchronously in the background.

Error Responses

409 Conflict · error

A transfer is already in progress for this server

{
  "error": "A transfer is already in progress for this server."
}

500 Internal Server Error · error

Failed to stop the server before initiating transfer

Transfer Process

When you initiate a transfer, Wings performs the following steps:

1. Server Stop

   Stops the server if it’s currently running (waits up to 15 seconds)

2. Archive Creation

   Creates a compressed archive of all server files

3. Stream to Destination

   Streams the archive to the destination node with progress updates every 5 seconds

4. Checksum Verification

   Sends a SHA-256 checksum for the destination to verify data integrity

The source node does not send a success status to the panel. Only the destination node reports success. If the transfer fails, the source node notifies the panel to reset the transfer state.

Example Request

cURL

curl -X POST https://wings.example.com/api/servers/12345678-1234-1234-1234-123456789012/transfer \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://destination.example.com/api/transfers",
    "token": "Bearer DESTINATION_JWT_TOKEN",
    "server": {
      "uuid": "12345678-1234-1234-1234-123456789012",
      "start_on_completion": false
    }
  }'

JavaScript

const response = await fetch(
  'https://wings.example.com/api/servers/12345678-1234-1234-1234-123456789012/transfer',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://destination.example.com/api/transfers',
      token: 'Bearer DESTINATION_JWT_TOKEN',
      server: {
        uuid: '12345678-1234-1234-1234-123456789012',
        start_on_completion: false
      }
    })
  }
);

Python

import requests

response = requests.post(
    'https://wings.example.com/api/servers/12345678-1234-1234-1234-123456789012/transfer',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'url': 'https://destination.example.com/api/transfers',
        'token': 'Bearer DESTINATION_JWT_TOKEN',
        'server': {
            'uuid': '12345678-1234-1234-1234-123456789012',
            'start_on_completion': False
        }
    }
)

Example Response

HTTP/1.1 202 Accepted

Monitoring Transfer Progress

You can monitor transfer progress through the server’s WebSocket connection. The transfer system publishes events:

• Transfer logs: Real-time progress messages (upload percentage, status updates)
• Transfer status: Current status (pending, processing, cancelling, cancelled, failed, completed)

Related Endpoints

Receive Transfer

Receive an incoming server transfer

Cancel Transfer

Cancel an outgoing server transfer