Skip to main content

​
Endpoint

POST /api/servers/:server/files/write

​
Authentication

Requires Bearer token authentication via the Authorization header.

​
Path Parameters

​
server
string
required
The UUID of the server

​
Query Parameters

​
file
string
required
The file path to write (relative to server root)

​
Request Body

Raw file contents to write. The Content-Type should be set appropriately for the file being written.

​
Response

Returns 204 No Content on success.

​
Example Request

curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/write?file=server.properties" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: text/plain" \
  -d "gamemode=survival
difficulty=normal
motd=My Minecraft Server"

​
Behavior

  • Creates the file if it doesn’t exist
  • Overwrites the file completely if it already exists
  • Creates parent directories automatically if they don’t exist
  • Sets appropriate file permissions based on server user configuration
  • Path traversal is prevented
  • Ignored files (.pteroignore) cannot be written
This operation completely overwrites the target file. There is no backup or undo functionality.

​
Error Responses

Missing or invalid Bearer token
File is on the ignore list (.pteroignore) or path traversal attempt detected
Server does not exist
Failed to write file (disk full, permission error, etc.)

​
Use Cases

  • Update configuration files
  • Modify server settings
  • Create new script files
  • Edit whitelist/ban lists

​
Source Reference

Implementation: router/router_server_files.go (postServerWriteFile function)

Build docs developers (and LLMs) love

Get started for freeTalk to us