# Files endpoints (Client API: game servers)

> 30 FeatherPanel Client API: game servers endpoints from user/server/files.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Source: https://featherpanel.com/docs/api/reference/user/server/files/

Defined in [`backend/app/routes/user/server/files.php`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php). Authentication used here: **Server access**. Read [Authentication](https://featherpanel.com/docs/api/authentication/) for how to send credentials and [Rate limits and errors](https://featherpanel.com/docs/api/rate-limits-and-errors/) for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

## Endpoints

### GET `/api/user/servers/{uuidShort}/files`

- Auth: Server access
- Default rate limit: 60 / minute (`user-server-files`)
- Route name: `session-server-files`
- Controller: [`ServerFilesController::getFiles`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L27)

**Get server files** Retrieve directory contents for a specific server path. Lists files and directories with their properties.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `path` | query | string | no | Directory path to list |
| `search` | query | string | no | Case-insensitive filename substring filter applied before the list item limit |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `contents` | ServerFileItem\[\] |  |
| `limited` | boolean | True when more matching items exist beyond the returned limit |
| `limit` | integer | Maximum number of items returned |
| `total` | integer | Number of matching items before applying the limit |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/files" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Files retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to fetch files

### GET `/api/user/servers/{uuidShort}/archive-list`

- Auth: Server access
- Default rate limit: 60 / minute (`user-server-files`)
- Route name: `session-server-archive-list`
- Controller: [`ServerFilesController::listArchiveDirectory`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L45)

**List directory inside an archive** Browse supported archives (zip, tar, …) on the server without extracting them.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes |  |
| `path` | query | string | no |  |
| `file` | query | string | yes |  |
| `archive_path` | query | string | no |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/archive-list?file=$FILE" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Archive listing retrieved · `400` Bad request · `403` Forbidden · `500` Internal server error

### GET `/api/user/servers/{uuidShort}/search-files`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-files`)
- Route name: `session-server-search-files`
- Controller: [`ServerFilesController::searchFiles`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L63)

**Search files with advanced filters** Search server files by path patterns, content text and size constraints.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes |  |
| `directory` | query | string | no |  |
| `pattern` | query | string | no |  |
| `include` | query | string | no |  |
| `exclude` | query | string | no |  |
| `case_insensitive` | query | boolean | no |  |
| `content` | query | string | no |  |
| `content_case_insensitive` | query | boolean | no |  |
| `min_size` | query | integer | no |  |
| `max_size` | query | integer | no |  |
| `max_content_size` | query | integer | no |  |
| `include_oversized` | query | boolean | no |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/search-files" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Search completed successfully · `400` Bad request · `401` Unauthorized · `403` Forbidden · `500` Internal server error

### GET `/api/user/servers/{uuidShort}/file`

- Auth: Server access
- Default rate limit: 60 / minute (`user-server-files`)
- Route name: `session-server-file`
- Controller: [`ServerFilesController::getFile`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L81)

**Get file content** Retrieve the raw content of a specific file with appropriate MIME type headers.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `path` | query | string | yes | File path to read |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/file?path=$PATH" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` File content retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server, node, or file not found · `500` Internal server error - Failed to fetch file

### GET `/api/user/servers/{uuidShort}/file-hash`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-files`)
- Route name: `session-server-file-hash`
- Controller: [`ServerFilesController::getFileHashes`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L100)

**Get file hashes** Calculate and return hashes for a file on the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `path` | query | string | yes | File path to hash |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/file-hash?path=$PATH" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` File hashes calculated successfully · `400` Bad request - Missing file path · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server, node, or file not found · `500` Internal server error - Failed to hash file

### POST `/api/user/servers/{uuidShort}/write-file`

- Auth: Server access
- Route name: `session-server-write-file`
- Controller: [`ServerFilesController::writeFile`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L119)

**Write file content** Write raw content to a file on the server. Content-Type must not be application/json. Send empty body to clear file contents.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `path` | query | string | yes | File path to write to |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/write-file?path=$PATH" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:file:saved`](https://featherpanel.com/docs/plugins/events/server/#server-file-written)

Responses: `200` File written successfully · `400` Bad request - Missing UUID or invalid content type · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `415` Unsupported media type - JSON content type not allowed · `500` Internal server error - Failed to write file

### PUT `/api/user/servers/{uuidShort}/rename`

- Auth: Server access
- Route name: `session-server-rename`
- Controller: [`ServerFilesController::renameFileOrFolder`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L132)

**Rename files or folders** Rename multiple files or folders on the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`RenameRequest`](https://featherpanel.com/docs/api/schemas/#schema-renamerequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | object\[\] | yes | Array of rename operations |
| `root` | string | yes | Root directory path |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X PUT "$PANEL_URL/api/user/servers/$UUID_SHORT/rename" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"files":[],"root":""}'
```

Plugin events: [`featherpanel:user:server:file:renamed`](https://featherpanel.com/docs/plugins/events/server/#server-file-renamed)

Responses: `200` Files renamed successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to rename files

### DELETE `/api/user/servers/{uuidShort}/delete-files`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-files`)
- Route name: `session-server-delete-files`
- Controller: [`ServerFilesController::deleteFiles`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L145)

**Delete files** Delete multiple files or folders from the server. This action cannot be undone.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`FileOperationRequest`](https://featherpanel.com/docs/api/schemas/#schema-fileoperationrequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | string\[\] | yes | Array of file paths |
| `root` | string | yes | Root directory path |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/user/servers/$UUID_SHORT/delete-files" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"files":[],"root":""}'
```

Plugin events: [`featherpanel:user:server:files:deleted`](https://featherpanel.com/docs/plugins/events/server/#server-files-deleted)

Responses: `200` Files deleted successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to delete files

### GET `/api/user/servers/{uuidShort}/trash`

- Auth: Server access
- Default rate limit: 60 / minute (`user-server-files`)
- Route name: `session-server-trash-list`
- Controller: [`ServerFilesController::listTrash`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L160)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | \- | yes |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/trash" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

### POST `/api/user/servers/{uuidShort}/trash/restore`

- Auth: Server access
- Default rate limit: 20 / minute (`user-server-files`)
- Route name: `session-server-trash-restore`
- Controller: [`ServerFilesController::restoreTrash`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L175)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | \- | yes |  |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/trash/restore" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

### POST `/api/user/servers/{uuidShort}/trash/delete`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-files`)
- Route name: `session-server-trash-delete`
- Controller: [`ServerFilesController::deleteTrashEntries`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L190)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | \- | yes |  |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/trash/delete" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

### POST `/api/user/servers/{uuidShort}/trash/empty`

- Auth: Server access
- Default rate limit: 5 / minute (`user-server-files`)
- Route name: `session-server-trash-empty`
- Controller: [`ServerFilesController::emptyTrash`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L205)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | \- | yes |  |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/trash/empty" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

### POST `/api/user/servers/{uuidShort}/wipe-all-files`

- Auth: Server access
- Default rate limit: 2 / minute (`user-server-files`)
- Route name: `session-server-wipe-all-files`
- Controller: [`ServerFilesController::wipeAllFiles`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L220)

**Wipe all server files** Delete all files and folders in the server root directory. This action cannot be undone.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |
| `deleted_count` | integer | Number of files/folders deleted |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/wipe-all-files" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:files:deleted`](https://featherpanel.com/docs/plugins/events/server/#server-files-deleted)

Responses: `200` All files wiped successfully · `400` Bad request - Missing UUID · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server or missing file.delete permission · `404` Not found - Server or node not found · `500` Internal server error - Failed to wipe files

### POST `/api/user/servers/{uuidShort}/copy-files`

- Auth: Server access
- Route name: `session-server-copy-files`
- Controller: [`ServerFilesController::copyFiles`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L235)

**Copy files** Copy multiple files or folders to a new location on the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`CopyRequest`](https://featherpanel.com/docs/api/schemas/#schema-copyrequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | string\[\] | yes | Array of file paths to copy |
| `location` | string | yes | Destination location |
| `name` | string | no | Optional destination name (Calagopus) |
| `overwrite` | boolean | no | Overwrite existing destination (Calagopus) |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/copy-files" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"files":[],"location":"","name":"","overwrite":false}'
```

Plugin events: [`featherpanel:server:files:copy`](https://featherpanel.com/docs/plugins/events/server/#server-files-copied)

Responses: `200` Files copied successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to copy files

### POST `/api/user/servers/{uuidShort}/create-directory`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-files`)
- Route name: `session-server-create-directory`
- Controller: [`ServerFilesController::createDirectory`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L248)

**Create directory** Create a new directory on the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`CreateDirectoryRequest`](https://featherpanel.com/docs/api/schemas/#schema-createdirectoryrequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Directory name |
| `path` | string | yes | Parent directory path |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/create-directory" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","path":""}'
```

Plugin events: [`featherpanel:user:server:directory:created`](https://featherpanel.com/docs/plugins/events/server/#server-directory-created)

Responses: `200` Directory created successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to create directory

### POST `/api/user/servers/{uuidShort}/compress-files`

- Auth: Server access
- Default rate limit: 5 / minute (`user-server-files`)
- Route name: `session-server-compress-files`
- Controller: [`ServerFilesController::compressFiles`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L263)

**Compress files** Compress multiple files or folders into an archive.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`CompressRequest`](https://featherpanel.com/docs/api/schemas/#schema-compressrequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | string\[\] | yes | Array of file paths |
| `root` | string | yes | Root directory path |
| `name` | string | no | Archive name (optional, auto-generated if not provided) |
| `extension` | string | no | Archive type: zip, tar.gz, tgz, tar.bz2, tbz2, tar.xz, txz |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/compress-files" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"files":[],"root":"","name":"","extension":""}'
```

Plugin events: [`featherpanel:server:file:compress`](https://featherpanel.com/docs/plugins/events/server/#server-file-compressed)

Responses: `200` Files compressed successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to compress files

### POST `/api/user/servers/{uuidShort}/decompress-archive`

- Auth: Server access
- Default rate limit: 20 / minute (`user-server-files`)
- Route name: `session-server-decompress-archive`
- Controller: [`ServerFilesController::decompressArchive`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L278)

**Decompress archive** Decompress an archive file on the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`DecompressRequest`](https://featherpanel.com/docs/api/schemas/#schema-decompressrequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | string | yes | Archive file path |
| `root` | string | yes | Root directory path |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/decompress-archive" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"file":"","root":""}'
```

Plugin events: [`featherpanel:server:file:decompress`](https://featherpanel.com/docs/plugins/events/server/#server-file-decompressed)

Responses: `200` Archive decompressed successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to decompress archive

### POST `/api/user/servers/{uuidShort}/extract-archive-selection`

- Auth: Server access
- Default rate limit: 20 / minute (`user-server-files`)
- Route name: `session-server-extract-archive-selection`
- Controller: [`ServerFilesController::extractArchiveSelection`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L293)

**Extract selected paths from an archive** Extract specific files or directories from an on-disk archive into a destination folder without unpacking the whole archive.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `root` | string | yes | Directory on the server that contains the archive |
| `file` | string | yes | Archive file name relative to root |
| `destination` | string | yes | Destination directory relative to server root (use empty string for /) |
| `entries` | string\[\] | yes | Paths inside the archive to extract |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/extract-archive-selection" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"root":"","file":"","destination":"","entries":[]}'
```

Responses: `200` Extraction started or completed successfully · `400` Bad request · `403` Forbidden · `500` Internal server error

### POST `/api/user/servers/{uuidShort}/change-permissions`

- Auth: Server access
- Default rate limit: 5 / minute (`user-server-files`)
- Route name: `session-server-change-permissions`
- Controller: [`ServerFilesController::changeFilePermissions`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L308)

**Change file permissions** Change permissions for multiple files or folders on the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`FileOperationRequest`](https://featherpanel.com/docs/api/schemas/#schema-fileoperationrequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | string\[\] | yes | Array of file paths |
| `root` | string | yes | Root directory path |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/change-permissions" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"files":[],"root":""}'
```

Plugin events: [`featherpanel:server:file:permissions`](https://featherpanel.com/docs/plugins/events/server/#server-file-permissions-changed)

Responses: `200` File permissions changed successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to change permissions

### POST `/api/user/servers/{uuidShort}/pull-file`

- Auth: Server access
- Route name: `session-server-pull-file`
- Controller: [`ServerFilesController::pullFile`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L323)

**Pull file from URL** Download a file from a URL to the server. Can run in foreground or background.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

Request body: [`PullFileRequest`](https://featherpanel.com/docs/api/schemas/#schema-pullfilerequest) (application/json)

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string (uri) | yes | URL to download from |
| `root` | string | yes | Destination directory path |
| `fileName` | string | no | Custom filename |
| `foreground` | boolean | no | Run in foreground |
| `useHeader` | boolean | no | Use headers |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/pull-file" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url":"","root":"","fileName":"","foreground":false,"useHeader":false}'
```

Responses: `200` File pull initiated successfully · `400` Bad request - Missing UUID or invalid request body · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to pull file

### GET `/api/user/servers/{uuidShort}/downloads-list`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-files`)
- Route name: `session-server-downloads-list`
- Controller: [`ServerFilesController::getDownloadsList`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L336)

**Get downloads list** Retrieve the list of active download processes for the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/downloads-list" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Downloads list retrieved successfully · `400` Bad request - Missing or invalid UUID short · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to get downloads list

### DELETE `/api/user/servers/{uuidShort}/delete-pull-process/{pullId}`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-files`)
- Route name: `session-server-delete-pull-process`
- Controller: [`ServerFilesController::deletePullProcess`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L351)

**Delete pull process** Cancel and delete an active download process.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `pullId` | path | string | yes | Pull process ID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X DELETE "$PANEL_URL/api/user/servers/$UUID_SHORT/delete-pull-process/$PULL_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:pull:deleted`](https://featherpanel.com/docs/plugins/events/server/#server-pull-process-deleted)

Responses: `200` Pull process deleted successfully · `400` Bad request - Missing parameters · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server, node, or pull process not found · `500` Internal server error - Failed to delete pull process

### POST `/api/user/servers/{uuidShort}/share-file`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-files`)
- Route name: `session-server-share-file`
- Controller: [`ServerFilesController::shareFile`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L371)

**Share a server file via temp uploads** Uploads a server file from Wings as a temp upload (multipart) and returns a public share URL and delete key. Large files may return a background job identifier; poll share-jobs until complete.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Body field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | string | yes | Path to the file on the server |
| `ttl_days` | integer | yes | How long the share remains available |
| `password` | string | no | Optional download password (min 4 chars) |
| `delete_key` | string | no | Optional custom delete key (min 8 chars) |
| `background` | boolean | no | Force background upload even for small files |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/share-file" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"file":"","ttl_days":0,"password":"","delete_key":"","background":false}'
```

Responses: `200` File shared successfully · `202` Background share started · `400` Bad request · `401` Unauthorized · `403` Forbidden · `404` Not found · `500` Internal server error

### GET `/api/user/servers/{uuidShort}/share-jobs`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-files`)
- Route name: `session-server-share-jobs`
- Controller: [`ServerFilesController::getShareJobs`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L386)

**List temp upload share jobs** Retrieve active temp upload share jobs for the server.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/share-jobs" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Share jobs retrieved successfully · `401` Unauthorized · `403` Forbidden · `500` Internal server error

### DELETE `/api/user/servers/{uuidShort}/share-jobs/{shareId}`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-files`)
- Route name: `session-server-delete-share-job`
- Controller: [`ServerFilesController::deleteShareJob`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L401)

**Cancel a temp upload share job** Cancels an in-progress temp upload share job.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `shareId` | path | string | yes | Share job identifier |

```bash
curl -X DELETE "$PANEL_URL/api/user/servers/$UUID_SHORT/share-jobs/$SHARE_ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Share job cancelled · `401` Unauthorized · `403` Forbidden · `500` Internal server error

### GET `/api/user/servers/{uuidShort}/upload-file`

- Auth: Server access
- Default rate limit: 300 / minute (`user-server-files`)
- Route name: `session-server-upload-file-url`
- Controller: [`ServerFilesController::getUploadUrl`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L421)

**Get file upload URL** Generate a secure one-time Wings upload URL with JWT token authentication. The browser uploads directly to Wings (multipart), avoiding PHP body/memory limits and panel proxy timeouts.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `upload_url` | string | Signed Wings file upload URL |
| `expires_in` | integer | Token lifetime in seconds |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/upload-file" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Upload URL generated successfully · `400` Bad request - Missing UUID · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to generate upload URL

### POST `/api/user/servers/{uuidShort}/upload-file`

- Auth: Server access
- Default rate limit: 30 / minute (`user-server-files`)
- Route name: `session-server-upload-file`
- Controller: [`ServerFilesController::uploadFile`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L436)

**Upload file** Upload a file to the server. Content-Type must not be application/json.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `path` | query | string | yes | Destination directory path |
| `filename` | query | string | no | Filename for the uploaded file |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `message` | string | Success message |

```bash
curl -X POST "$PANEL_URL/api/user/servers/$UUID_SHORT/upload-file?path=$PATH" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Plugin events: [`featherpanel:user:server:file:uploaded`](https://featherpanel.com/docs/plugins/events/server/#server-file-uploaded)

Responses: `200` File uploaded successfully · `400` Bad request - Missing UUID, empty content, or invalid content type · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `415` Unsupported media type - JSON content type not allowed · `500` Internal server error - Failed to upload file

### GET `/api/user/servers/{uuidShort}/download-file`

- Auth: Server access
- Default rate limit: 20 / minute (`user-server-files`)
- Route name: `session-server-download-file`
- Controller: [`ServerFilesController::downloadFile`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L451)

**Get file download URL** Generate a secure one-time Wings download URL for a server file with JWT token authentication (same pattern as backup downloads).

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `path` | query | string | yes | File path to download |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `download_url` | string | Signed Wings file download URL |
| `expires_in` | integer | Token lifetime in seconds |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/download-file?path=$PATH" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Download URL generated successfully · `400` Bad request - Missing UUID or file path · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server, node, or file not found · `500` Internal server error - Failed to generate download URL

### GET `/api/user/servers/{uuidShort}/download-directory`

- Auth: Server access
- Default rate limit: 10 / minute (`user-server-files`)
- Route name: `session-server-download-directory`
- Controller: [`ServerFilesController::downloadDirectory`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L466)

**Get directory download URL** Generate a secure Wings download URL that archives and streams a directory (Calagopus).

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | string | yes | Server short UUID |
| `path` | query | string | yes | Directory path to download |

| Response `data` field | Type | Description |
| --- | --- | --- |
| `download_url` | string | Signed Wings directory download URL |
| `expires_in` | integer | Token lifetime in seconds |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/download-directory?path=$PATH" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```

Responses: `200` Download URL generated successfully · `400` Bad request - Missing UUID or directory path · `401` Unauthorized - User not authenticated · `403` Forbidden - Access denied to server · `404` Not found - Server or node not found · `500` Internal server error - Failed to generate download URL · `501` Daemon feature unsupported

### GET `/api/user/servers/{uuidShort}/file-fingerprints`

- Auth: Server access
- Default rate limit: 20 / minute (`user-server-files`)
- Route name: `session-server-file-fingerprints`
- Controller: [`ServerFilesController::getFileFingerprints`](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/Controllers/User/Server/Files/ServerFilesController.php)
- [route source](https://github.com/MythicalLTD/FeatherPanel/blob/15b94e9fc9df233123706b47c42728b81e48cb3d/backend/app/routes/user/server/files.php#L481)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuidShort` | path | \- | yes |  |

```bash
curl -X GET "$PANEL_URL/api/user/servers/$UUID_SHORT/file-fingerprints" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"
```