Skip to main content

​
Endpoint

POST /api/servers/:server/files/pull

​
Configuration Requirement

This endpoint must be explicitly enabled in the Wings configuration. It is disabled by default for security reasons. In config.yml: 
api:
  disable_remote_download: false  # Must be false to enable remote downloads
Remote file downloads can pose security risks if not properly validated. Only enable this feature if you trust the users who have access to your servers.

​
Authentication

Requires Bearer token authentication via the Authorization header.

​
Path Parameters

​
server
string
required
The UUID of the server

​
Request Body

​
url
string
required
The remote URL to download from (must be HTTP/HTTPS)
​
directory
string
required
The destination directory where the file will be saved (relative to server root)
​
filename
string
Optional custom filename. If not provided, filename is extracted from the URL or Content-Disposition header.
​
use_header
boolean
default:"false"
Whether to use the filename from the Content-Disposition header if available
​
foreground
boolean
default:"false"
Whether to download in the foreground (blocks until complete) or background

​
Response

Returns 204 No Content on success (background download) or after completion (foreground download).

​
Example Request

curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/pull" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/plugins/MyPlugin.jar",
    "directory": "/plugins",
    "foreground": false
  }'

​
Behavior

  • Downloads are performed asynchronously by default (foreground: false)
  • Foreground downloads block until complete, background downloads return immediately
  • Download progress is published via WebSocket events
  • File is written directly to disk (no memory buffering of entire file)
  • Supports redirects (follows 3xx responses)
  • User-Agent is set to Pterodactyl Wings
  • Timeout: 15 minutes for the entire download
  • Maximum file size: Limited by available disk space
  • Existing files with the same name are overwritten
  • Path traversal is prevented
Monitor download progress through the server’s WebSocket connection. Progress events include download speed and bytes downloaded.

​
Error Responses

Invalid URL format or missing required fields
Missing or invalid Bearer token
Remote downloads are disabled in Wings configuration
Server does not exist or remote file not found
Failed to download file (network error, disk full, etc.)

​
Security Considerations

  • SSRF Prevention: Wings does not validate remote URLs. Malicious users could potentially download from internal network resources.
  • Disk Usage: Large downloads can fill up disk space
  • Malware: Downloaded files are not scanned for malware
  • Rate Limiting: No built-in rate limiting for remote downloads
Consider the security implications before enabling remote downloads. Use firewall rules and network policies to restrict access to sensitive internal resources.

​
Use Cases

  • Download plugins from remote repositories
  • Import world maps from CDN
  • Fetch configuration files from GitHub
  • Download mod packs
  • Import database dumps

​
Source Reference

Implementation: router/router_server_files.go (postServerPullRemoteFile function)

Build docs developers (and LLMs) love

Get started for freeTalk to us