Skip to main content

​
Endpoint

PUT /api/servers/:server/files/rename

​
Authentication

Requires Bearer token authentication via the Authorization header.

​
Path Parameters

​
server
string
required
The UUID of the server

​
Request Body

​
root
string
required
The root directory for the rename operations (all paths are relative to this)
​
files
array
required
Array of file rename operations

​
Response

Returns 204 No Content on success.

​
Example Request

curl -X PUT "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/rename" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "root": "/",
    "files": [
      {
        "from": "old-config.yml",
        "to": "config.yml"
      }
    ]
  }'

​
Behavior

  • Operations are performed concurrently for better performance
  • Both files and directories can be renamed/moved
  • Moving to a different directory requires the full path in the to field
  • If the source file doesn’t exist, the operation is skipped (no error)
  • Parent directories in the destination path are created automatically
  • Ignored files (.pteroignore) cannot be renamed or moved
  • Path traversal is prevented
If the destination file already exists, the operation will fail with a 400 error.

​
Error Responses

Destination file already exists
Missing or invalid Bearer token
File is on the ignore list or path traversal attempt
Server does not exist
Empty files array provided
Failed to rename file (permission error, etc.)

​
Use Cases

  • Rename configuration files
  • Move files between directories
  • Organize server files into folders
  • Create backup copies (rename to .bak)
  • Batch rename operations

​
Source Reference

Implementation: router/router_server_files.go:94-158 (putServerRenameFiles function)

Build docs developers (and LLMs) love

Get started for freeTalk to us