File Management

The file management API provides server-side file operations for SFTP, SMB, and FTP connections. All endpoints require a valid connectionId and are scoped to that connection's configured credentials.

All file management endpoints require authentication.

---

SFTP

Base path: /api/v1/sftp/:connectionId

POST /sftp/:connectionId/list

List the contents of a directory.

Request body

{ "path": "/var/www" }

Response

{
  "files": [
    {
      "filename": "html",
      "fileAttributes": {
        "size": 4096,
        "isDirectory": true,
        "permissions": "drwxr-xr-x",
        "mode": 16877,
        "uid": 33,
        "gid": 33,
        "atime": "2024-01-01T00:00:00.000Z",
        "mtime": "2024-01-01T00:00:00.000Z"
      }
    }
  ]
}

---

GET /sftp/:connectionId/download

Download a file from the remote server.

Query parameters

Param	Required	Description
path	Yes	Absolute path on the remote server

Response: File stream.

---

POST /sftp/:connectionId/upload

Upload a file to the remote server.

Query parameters

Param	Required	Description
path	Yes	Destination path on the remote server

Body: Raw file bytes.

Response

{ "success": true }

---

POST /sftp/:connectionId/mkdir

Create a directory.

Request body

{ "path": "/var/www/new-dir" }

Response

{ "success": true }

---

DELETE /sftp/:connectionId/file

Delete a file or directory.

Query parameters

Param	Required	Description
path	Yes	Absolute path to delete

Response

{ "success": true }

---

POST /sftp/:connectionId/rename

Rename or move a file or directory.

Request body

{ "oldPath": "/var/www/old.html", "newPath": "/var/www/new.html" }

Response

{ "success": true }

---

POST /sftp/:connectionId/stat

Get detailed info about a file or directory.

Request body

{ "path": "/var/www/html/index.html" }

Response

{
  "size": 12400,
  "mode": 33188,
  "permissions": "-rw-r--r--",
  "uid": 33,
  "gid": 33,
  "atime": "2024-01-01T00:00:00.000Z",
  "mtime": "2024-01-01T00:00:00.000Z",
  "isDirectory": false
}

---

POST /sftp/:connectionId/chmod

Change file or directory permissions.

Request body

{ "path": "/var/www/html/script.sh", "mode": 493 }

mode is a Unix permission integer. For example, 493 = 0755 (rwxr-xr-x).

Response

{ "success": true }

---

POST /sftp/:connectionId/copy

Server-side copy of a file or directory.

Request body

{ "srcPath": "/var/www/html/index.html", "destPath": "/var/www/html/index.bak.html" }

Response

{ "success": true }

---

SMB

Base path: /api/v1/smb/:connectionId

POST /smb/:connectionId/list

List the contents of a directory.

Request body

{ "path": "/share/documents" }

Response

{
  "files": [
    {
      "filename": "report.docx",
      "fileAttributes": { "size": 45056, "isDirectory": false }
    }
  ]
}

---

GET /smb/:connectionId/download

Download a file.

Query parameters

Param	Required	Description
path	Yes	Path on the SMB share

Response: File stream.

---

POST /smb/:connectionId/upload

Upload a file.

Query parameters

Param	Required	Description
path	Yes	Destination path on the SMB share

Body: Raw file bytes.

Response

{ "success": true }

---

POST /smb/:connectionId/mkdir

Create a directory.

Request body

{ "path": "/share/new-folder" }

Response

{ "success": true }

---

DELETE /smb/:connectionId/file

Delete a file or directory.

Query parameters

Param	Required	Description
path	Yes	Path to delete

Response

{ "success": true }

---

POST /smb/:connectionId/rename

Rename or move a file or directory.

Request body

{ "oldPath": "/share/old-name.docx", "newPath": "/share/new-name.docx" }

Response

{ "success": true }

---

FTP

Base path: /api/v1/ftp/:connectionId

POST /ftp/:connectionId/list

List the contents of a directory.

Request body

{ "path": "/public" }

Response

{
  "files": [
    {
      "filename": "data.csv",
      "fileAttributes": { "size": 8192, "isDirectory": false }
    }
  ]
}

---

GET /ftp/:connectionId/download

Download a file.

Query parameters

Param	Required	Description
path	Yes	Remote file path

Response: File stream.

---

POST /ftp/:connectionId/upload

Upload a file.

Query parameters

Param	Required	Description
path	Yes	Remote destination path

Body: Raw file bytes.

Response

{ "success": true }

---

POST /ftp/:connectionId/mkdir

Create a directory.

Request body

{ "path": "/public/new-dir" }

Response

{ "success": true }

---

DELETE /ftp/:connectionId/file

Delete a file or directory.

Query parameters

Param	Required	Description
path	Yes	Path to delete

Response

{ "success": true }

---

POST /ftp/:connectionId/rename

Rename or move a file or directory.

Request body

{ "oldPath": "/public/old.csv", "newPath": "/public/new.csv" }

Response

{ "success": true }

---

POST /ftp/:connectionId/stat

Get file info.

Request body

{ "path": "/public/data.csv" }

Response

{ "size": 8192, "mtime": "2024-01-01T00:00:00.000Z", "isDirectory": false }