Update Configuration

Endpoint

POST /api/update

Updates the running configuration for the Wings instance. This endpoint allows the Pterodactyl Panel to push configuration updates to Wings without requiring a restart. The new configuration is validated, written to disk, and applied to the running instance.

Authentication

This endpoint requires authentication using a Bearer token in the Authorization header.

Authorization: Bearer <your-token>

Request Body

The request body should contain a complete Wings configuration object in JSON format. This follows the same structure as the config.yml file.

debug

boolean

Enable debug mode for verbose logging

app_name

string

default:"Pterodactyl"

Application name for Wings

uuid

string

required

Unique identifier for this node in the Panel

token_id

string

required

Token identifier for authentication

token

string

required

Authentication token for API requests

api

object

required

API server configuration

Show api properties

api.host

string

default:"0.0.0.0"

Host address to bind the API server to

api.port

integer

default:"8080"

Port to bind the API server to

api.ssl

object

SSL/TLS configuration

Show ssl properties

api.ssl.enabled

boolean

Enable SSL/TLS

api.ssl.cert

string

Path to SSL certificate file

api.ssl.key

string

Path to SSL private key file

api.upload_limit

integer

default:"100"

Maximum file upload size in MB

api.trusted_proxies

array

List of trusted proxy IP addresses

api.disable_remote_download

boolean

Disable remote file download functionality

system

object

required

System configuration settings

Show system properties

system.root_directory

string

default:"/var/lib/pterodactyl"

Root directory for all Pterodactyl data

system.log_directory

string

default:"/var/log/pterodactyl"

Directory for Wings logs

system.data

string

default:"/var/lib/pterodactyl/volumes"

Directory for server data

system.archive_directory

string

default:"/var/lib/pterodactyl/archives"

Directory for server transfer archives

system.backup_directory

string

default:"/var/lib/pterodactyl/backups"

Directory for server backups

system.tmp_directory

string

default:"/tmp/pterodactyl"

Temporary directory for Wings operations

system.username

string

default:"pterodactyl"

System user that owns server files

system.timezone

string

Timezone for containers (auto-detected if not set)

docker

object

required

Docker configuration settings (see Docker Settings for details)

remote

string

required

Panel URL for API communication

remote_query

object

Remote query configuration

Show remote_query properties

remote_query.timeout

integer

default:"30"

Request timeout in seconds for Panel API calls

remote_query.boot_servers_per_page

integer

default:"50"

Number of servers to load per request during boot

allowed_mounts

array

List of allowed host paths for server mounts

allowed_origins

array

Additional CORS allowed origins

ignore_panel_config_updates

boolean

default:"false"

When enabled, configuration updates from the Panel are ignored

Response

applied

boolean

Indicates whether the configuration update was applied. Returns false if ignore_panel_config_updates is enabled in the current configuration.

Behavior

Configuration Update Flow

Validation: The incoming configuration is validated and merged with defaults
SSL Certificate Handling: If SSL certificates use Let’s Encrypt default paths (/etc/letsencrypt/live/), the existing certificate paths are preserved to prevent overwriting manually configured locations
Disk Write: The configuration is written to disk at the config file location
Runtime Update: If the write succeeds, the global configuration state is updated
Response: Returns whether the update was applied

Ignored Updates

When ignore_panel_config_updates is set to true in the Wings configuration file, this endpoint will:

Return {"applied": false}
Not write any changes to disk
Not update the runtime configuration

This is useful for Wings instances that need to maintain custom configurations independent of Panel updates.

Configuration updates are applied immediately to the running Wings instance without requiring a restart. However, some changes (like port bindings) may not take full effect until Wings is restarted.

Example Requests

curl -X POST "https://wings.example.com/api/update" \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "3e3e4e5e-6f7f-8a8a-9b9b-0c0c0d0d0e0e",
    "token_id": "abc123",
    "token": "your-authentication-token",
    "api": {
      "host": "0.0.0.0",
      "port": 8080,
      "ssl": {
        "enabled": true,
        "cert": "/etc/letsencrypt/live/wings.example.com/fullchain.pem",
        "key": "/etc/letsencrypt/live/wings.example.com/privkey.pem"
      },
      "upload_limit": 100
    },
    "system": {
      "root_directory": "/var/lib/pterodactyl",
      "data": "/var/lib/pterodactyl/volumes",
      "username": "pterodactyl"
    },
    "remote": "https://panel.example.com"
  }'

Example Responses

{
  "applied": true
}

Error Responses

{
  "error": "Invalid JSON payload"
}

SSL Certificate Handling

The endpoint includes special logic for SSL certificates to prevent accidental overwrites:

// If the Panel sends Let's Encrypt default paths
if (config.api.ssl.key.startsWith('/etc/letsencrypt/live/')) {
  // Wings preserves existing custom certificate paths
  // This prevents overwriting manually configured SSL certificates
}

If you need to update SSL certificate paths, ensure they don’t use the default Let’s Encrypt location pattern, or manually update the configuration file.

Use Cases

Automated Panel Updates

The Pterodactyl Panel automatically calls this endpoint when node configuration is updated:

def update_node_configuration(node_id, new_config):
    """Called by Panel when admin updates node settings"""
    response = requests.post(
        f'https://{node.fqdn}:{node.port}/api/update',
        headers={'Authorization': f'Bearer {node.daemon_token}'},
        json=new_config
    )
    
    if response.json()['applied']:
        print(f'Configuration updated for node {node_id}')
    else:
        print(f'Node {node_id} is ignoring Panel configuration updates')

Manual Configuration Sync

You can manually sync configuration from your Panel to Wings:

#!/bin/bash
# Sync Wings configuration from Panel

curl -X POST "https://wings.example.com/api/update" \
  -H "Authorization: Bearer $(cat /etc/pterodactyl/config.yml | grep '^token:' | awk '{print $2}')" \
  -H "Content-Type: application/json" \
  -d @/tmp/new-config.json

Implementation Details

The configuration update process is implemented in router/router_system.go:122-158:

Check ignore flag: If IgnorePanelConfigUpdates is true, return {"applied": false} immediately
Parse JSON: Bind the incoming JSON to a Configuration struct
Preserve SSL paths: Check for Let’s Encrypt default paths and preserve existing custom paths
Write to disk: Call config.WriteToDisk() to persist the new configuration
Update runtime: Call config.Set() to apply changes to the running instance
Return result: Return {"applied": true} on success

The configuration file location is determined by the --config flag used when starting Wings. By default, this is /etc/pterodactyl/config.yml.

Security Considerations

This endpoint can modify critical Wings configuration. Ensure your authentication token is kept secure and only accessible by the Pterodactyl Panel.

The endpoint requires a valid Bearer token matching the configured AuthenticationToken
Configuration changes are written to disk with restricted file permissions
Invalid configurations will cause the request to fail without modifying the existing config
SSL certificate paths are validated and protected from accidental overwrites

Get System Information - Retrieve system and Wings version information
Get Servers - List all servers managed by this Wings instance

Configuration File - Complete configuration file reference
System Settings - System configuration options
SSL/TLS Configuration - SSL certificate setup

Getting Started

System

Servers

File Management

Backups

Transfers

Endpoint

Authentication

Request Body

Response

Behavior

Configuration Update Flow

Ignored Updates

Example Requests

Example Responses

Error Responses

SSL Certificate Handling

Use Cases

Automated Panel Updates

Manual Configuration Sync

Implementation Details

Security Considerations

Build docs developers (and LLMs) love

Getting Started

System

Servers

File Management

Backups

Transfers

​Endpoint

​Authentication

​Request Body

​Response

​Behavior

​Configuration Update Flow

​Ignored Updates

​Example Requests

​Example Responses

​Error Responses

​SSL Certificate Handling

​Use Cases

​Automated Panel Updates

​Manual Configuration Sync

​Implementation Details

​Security Considerations

​Related Endpoints

​Related Configuration

Build docs developers (and LLMs) love

Endpoint

Authentication

Request Body

Response

Behavior

Configuration Update Flow

Ignored Updates

Example Requests

Example Responses

Error Responses

SSL Certificate Handling

Use Cases

Automated Panel Updates

Manual Configuration Sync

Implementation Details

Security Considerations

Related Endpoints

Related Configuration