Skip to main content

​
Endpoint

POST /upload/file

​
Authentication

This endpoint uses JWT authentication via a signed upload URL token, not Bearer token authentication. The JWT token must be included in the query string as the token parameter.

​
Query Parameters

​
token
string
required
Signed JWT token authorizing the upload. Generated by the Panel.

​
JWT Payload

The JWT token must contain:
​
server_uuid
string
required
The UUID of the server
​
unique_id
string
Optional unique identifier for one-time use enforcement

​
Request Body

Multipart form data with file uploads.
​
files
file[]
required
One or more files to upload
​
directory
string
default:"/"
Target directory path (relative to server root)

​
Response

Returns 204 No Content on success.

​
Example Request

curl -X POST "https://wings.example.com/upload/file?token=SIGNED_JWT_TOKEN" \
  -F "files=@/path/to/local/file.txt" \
  -F "files=@/path/to/another/file.zip" \
  -F "directory=/uploads"

​
Behavior

  • Multiple files can be uploaded in a single request
  • Files are written to the specified directory
  • Parent directories are created automatically if they don’t exist
  • Existing files with the same name are overwritten
  • Upload size is limited by the upload_limit configuration (default: 100 MB)
  • JWT tokens can be marked as one-time use and will be invalidated after the first upload
  • Ignored files (.pteroignore) cannot be uploaded
The upload limit is configured in the Wings config.yml file under api.upload_limit. Large file uploads may time out based on network speed and server configuration.

​
Rate Limiting

Uploads are subject to Wings’ general rate limiting configuration. Very large or numerous uploads may be throttled.

​
Error Responses

Invalid multipart form data or missing files
Missing or invalid JWT token
File is on the ignore list or path traversal attempt
File exceeds upload_limit configuration
Failed to save file (disk full, permission error, etc.)

​
JWT Token Generation

Upload tokens are typically generated by the Pterodactyl Panel and passed to the client. The token should:
  • Include the server_uuid claim
  • Have a short expiration time (recommended: 5-15 minutes)
  • Optionally include a unique_id for one-time use

​
Source Reference

Implementation: router/router_server_files.go (postServerUploadFiles function)

Build docs developers (and LLMs) love

Get started for freeTalk to us