Skip to main content

​
Endpoint

GET /api/servers/:server/files/list-directory

​
Authentication

Requires Bearer token authentication via the Authorization header.

​
Path Parameters

​
server
string
required
The UUID of the server

​
Query Parameters

​
directory
string
default:"/"
The directory path to list (relative to server root). Defaults to root directory if not specified.

​
Response

Returns an array of file stat objects.
​
name
string
The name of the file or directory
​
mode
string
Unix file mode as a string
​
mode_bits
string
Unix file mode in octal notation
​
size
integer
Size of the file in bytes
​
is_file
boolean
Whether this entry is a file
​
is_symlink
boolean
Whether this entry is a symbolic link
​
mimetype
string
MIME type of the file (detected by file extension)
​
created_at
string
ISO 8601 timestamp of file creation
​
modified_at
string
ISO 8601 timestamp of last modification

​
Example Request

curl -X GET "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/list-directory?directory=/logs" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

​
Example Response

[
  {
    "name": "server.log",
    "mode": "-rw-r--r--",
    "mode_bits": "0644",
    "size": 524288,
    "is_file": true,
    "is_symlink": false,
    "mimetype": "text/plain",
    "created_at": "2024-01-15T10:30:00Z",
    "modified_at": "2024-01-15T14:25:00Z"
  },
  {
    "name": "backups",
    "mode": "drwxr-xr-x",
    "mode_bits": "0755",
    "size": 4096,
    "is_file": false,
    "is_symlink": false,
    "mimetype": "inode/directory",
    "created_at": "2024-01-10T08:00:00Z",
    "modified_at": "2024-01-15T12:00:00Z"
  }
]

​
Behavior

  • Files are sorted with directories first, then files alphabetically
  • Path traversal is prevented - attempts to access paths outside the server directory will fail
  • The directory path is relative to the server’s root directory
  • Symlinks are resolved but marked with is_symlink: true
  • Hidden files (starting with .) are included in the listing

​
Error Responses

Missing or invalid Bearer token
Server does not exist or directory not found
Failed to read directory contents

​
Source Reference

Implementation: router/router_server_files.go:78-86

Build docs developers (and LLMs) love

Get started for freeTalk to us