File Manager API: browse, upload, and edit remote files

The File Manager API provides SFTP-backed file operations on remote hosts. Every file operation requires an active SSH session created with POST /ssh/file_manager/ssh/connect. Sessions time out after 30 minutes of inactivity and are cleaned up automatically. All endpoints require JWT authentication via a jwt cookie or Authorization: Bearer <token> header.

Session management

Connect SSH session

POST /ssh/file_manager/ssh/connect Establishes an SSH/SFTP connection for file manager operations. Supports password, SSH key, OPKSSH, and keyboard-interactive authentication, as well as jump host chains and SOCKS5 proxies.

sessionId

string

required

Client-generated unique session identifier.

string

required

SSH server IP or hostname.

port

number

required

SSH server port.

username

string

required

SSH username.

hostId

number

Host ID from the Termix database. If provided without password/sshKey, credentials are resolved server-side.

password

string

SSH password for password authentication.

sshKey

string

PEM-encoded SSH private key for key-based authentication.

keyPassword

string

Passphrase for the private key.

authType

string

Authentication method: password, key, opkssh, or none (keyboard-interactive).

credentialId

number

Legacy credential ID to resolve from the database.

jumpHosts

object[]

Ordered list of jump hosts. Each object must have a hostId property.

useSocks5

boolean

Route the connection through a SOCKS5 proxy.

socks5Host

string

SOCKS5 proxy hostname.

socks5Port

number

SOCKS5 proxy port.

socks5Username

string

SOCKS5 proxy username.

socks5Password

string

SOCKS5 proxy password.

socks5ProxyChain

object[]

Ordered chain of SOCKS5 proxy nodes.

The response varies by authentication outcome:

status

string

"success" on immediate connection, or "auth_required" if keyboard-interactive auth is needed but no credentials are configured.

message

string

Human-readable status message.

connectionLogs

object[]

Structured connection log entries.

requires_totp

boolean

Present and true when TOTP is needed.

requires_warpgate

boolean

Present and true when Warpgate browser auth is needed.

sessionId

string

Echoed session ID, present with TOTP/Warpgate flows.

prompt

string

TOTP or keyboard-interactive prompt text.

url

string

Warpgate authentication URL.

securityKey

string

Warpgate security key.

Error responses

Status	Meaning
400	Missing required parameters, or invalid SSH key format.
401	Authentication required, or OPKSSH token missing.
500	SSH connection failed.

Example request

cURL

curl -X POST https://your-termix-host/ssh/file_manager/ssh/connect \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "fm_sess_abc",
    "hostId": 5,
    "ip": "192.168.1.10",
    "port": 22,
    "username": "ubuntu"
  }'

Verify TOTP

POST /ssh/file_manager/ssh/connect-totp Completes a pending file manager connection by verifying a TOTP code. Call this when the connect response includes requires_totp: true. The session must be verified within 3 minutes.

sessionId

string

required

Session ID from the connect call.

totpCode

string

required

One-time code.

Error responses

Status	Meaning
400	`sessionId` or `totpCode` missing.
401	Authentication required or TOTP code invalid.
404	TOTP session expired — reconnect.
408	TOTP session or verification timed out.

Complete Warpgate authentication

POST /ssh/file_manager/ssh/connect-warpgate Signals completion of Warpgate browser authentication. The Warpgate session expires after 5 minutes.

sessionId

string

required

Session ID from the connect call.

Disconnect SSH session

POST /ssh/file_manager/ssh/disconnect Terminates the SSH session and releases all SFTP resources.

sessionId

string

required

Session ID to close.

Check session status

GET /ssh/file_manager/ssh/status

sessionId

string

required

Session ID to check.

status

string

Always "success".

connected

boolean

Whether the session is currently connected.

Keep session alive

POST /ssh/file_manager/ssh/keepalive Resets the session idle timer and probes the underlying SFTP channel.

sessionId

string

required

Session ID.

status

string

Always "success".

connected

boolean

Session state.

lastActive

number

Updated last-active timestamp (milliseconds).

Set sudo password

POST /ssh/file_manager/sudo-password Stores a sudo password temporarily in the session memory for use with privileged file operations.

sessionId

string

required

Session ID.

password

string

required

Sudo password.

File operations

List directory

GET /ssh/file_manager/ssh/listFiles Lists files and directories at the given remote path using SFTP with fallback to ls -la.

sessionId

string

required

Session ID.

path

string

required

URL-encoded absolute path to list (e.g. /home/ubuntu).

files

object[]

Array of file/directory entries.

Show properties

name

string

Filename.

type

string

"file", "directory", or "link".

size

number

File size in bytes. undefined for directories.

modified

string

Last-modified timestamp in ls format.

permissions

string

Unix permission string (e.g. "-rw-r--r--").

owner

string

UID of the file owner.

group

string

GID of the file group.

linkTarget

string

Target path for symbolic links.

path

string

Full remote path to the entry.

executable

boolean

Whether the file is executable.

path

string

The path that was listed.

Error responses

Status	Meaning
400	Session ID missing or session not connected.
403	Session belongs to a different user.
409	A list request for the same path is already in progress.
500	SFTP or fallback command error.

Example request

cURL

curl -X GET "https://your-termix-host/ssh/file_manager/ssh/listFiles?sessionId=fm_sess_abc&path=%2Fhome%2Fubuntu" \
  -H "Authorization: Bearer <token>"

Identify symlink

GET /ssh/file_manager/ssh/identifySymlink Resolves the target and type of a symbolic link.

sessionId

string

required

Session ID.

path

string

required

URL-encoded path to the symlink.

Resolve path

GET /ssh/file_manager/ssh/resolvePath Resolves a potentially relative or symbolic path to its canonical absolute path.

sessionId

string

required

Session ID.

path

string

required

URL-encoded path to resolve.

Read file

GET /ssh/file_manager/ssh/readFile Reads the content of a remote file. Binary files are returned as base64-encoded strings; text files are returned as UTF-8.

sessionId

string

required

Session ID.

path

string

required

URL-encoded path to the file.

content

string

File content as a UTF-8 string or base64-encoded string.

isBinary

boolean

Whether the file was detected as binary.

encoding

string

"utf8" or "base64".

mimeType

string

Detected MIME type.

size

number

File size in bytes.

Write file

POST /ssh/file_manager/ssh/writeFile Creates or overwrites a file on the remote host.

sessionId

string

required

Session ID.

path

string

required

Absolute remote path to write.

content

string

required

File content as a UTF-8 string.

useSudo

boolean

Write via sudo if the file requires elevated privileges. Requires a sudo password to be set.

Upload file

POST /ssh/file_manager/ssh/uploadFile Uploads a binary file to the remote host. Send the file as an application/octet-stream body, with metadata in query parameters.

sessionId

string

required

Session ID.

path

string

required

URL-encoded remote destination path.

useSudo

boolean

Upload via sudo.

The request body must be raw binary (Content-Type: application/octet-stream). File size limit is 5 GB.

Download file

POST /ssh/file_manager/ssh/downloadFile Streams a file from the remote host to the client as a binary response.

sessionId

string

required

Session ID.

path

string

required

Absolute remote path of the file to download.

The response is the raw file binary with Content-Disposition: attachment headers.

Create file

POST /ssh/file_manager/ssh/createFile Creates an empty file at the specified remote path.

sessionId

string

required

Session ID.

path

string

required

Absolute remote path for the new file.

useSudo

boolean

Create via sudo.

Create folder

POST /ssh/file_manager/ssh/createFolder Creates a directory (and any necessary parent directories) at the specified remote path.

sessionId

string

required

Session ID.

path

string

required

Absolute remote path for the new directory.

useSudo

boolean

Create via sudo.

Delete item

DELETE /ssh/file_manager/ssh/deleteItem Deletes a file or directory. Directories are removed recursively.

This operation is irreversible. Files are permanently deleted, not moved to a trash folder.

sessionId

string

required

Session ID.

path

string

required

Absolute remote path to delete.

useSudo

boolean

Delete via sudo.

Rename item

PUT /ssh/file_manager/ssh/renameItem Renames or moves a file or directory to a new path on the same host.

sessionId

string

required

Session ID.

oldPath

string

required

Current absolute remote path.

newPath

string

required

New absolute remote path.

useSudo

boolean

Rename via sudo.

Move item

PUT /ssh/file_manager/ssh/moveItem Moves a file or directory to a different directory. Equivalent to mv on the remote host.

sessionId

string

required

Session ID.

sourcePath

string

required

Absolute remote path of the item to move.

destinationPath

string

required

Absolute remote path of the destination directory.

useSudo

boolean

Move via sudo.

Copy item

POST /ssh/file_manager/ssh/copyItem Copies a file or directory to a new location on the remote host.

sessionId

string

required

Session ID.

sourcePath

string

required

Source absolute path.

destinationPath

string

required

Destination absolute path.

useSudo

boolean

Copy via sudo.

Execute file

POST /ssh/file_manager/ssh/executeFile Executes a file on the remote host as a script or binary and returns the output.

sessionId

string

required

Session ID.

path

string

required

Absolute path of the file to execute.

args

string[]

Optional command-line arguments to pass.

useSudo

boolean

Execute via sudo.

Change permissions

POST /ssh/file_manager/ssh/changePermissions Changes the permissions (and optionally ownership) of a remote file or directory.

sessionId

string

required

Session ID.

path

string

required

Absolute remote path.

permissions

string

required

Octal permission string (e.g. "755") or symbolic permissions (e.g. "+x").

recursive

boolean

Apply permissions recursively to directories.

useSudo

boolean

Change permissions via sudo.

Extract archive

POST /ssh/file_manager/ssh/extractArchive Extracts a compressed archive on the remote host. Supported formats: .tar, .tar.gz, .tgz, .tar.bz2, .tar.xz, .zip.

sessionId

string

required

Session ID.

archivePath

string

required

Absolute path to the archive file.

destinationPath

string

required

Directory to extract into.

useSudo

boolean

Extract via sudo.

Compress files

POST /ssh/file_manager/ssh/compressFiles Compresses one or more files or directories into a new archive on the remote host.

sessionId

string

required

Session ID.

paths

string[]

required

Array of absolute remote paths to compress.

destinationPath

string

required

Absolute path for the output archive file (including filename and extension).

useSudo

boolean

Compress via sudo.

Overview

Endpoints

File Manager API: browse, upload, and edit remote files

Session management

Connect SSH session

Verify TOTP

Complete Warpgate authentication

Disconnect SSH session

Check session status

Keep session alive

Set sudo password

File operations

List directory

Identify symlink

Resolve path

Read file

Write file

Upload file

Download file

Create file

Create folder

Delete item

Rename item

Move item

Copy item

Execute file

Change permissions

Extract archive

Compress files

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Session management

​Connect SSH session

​Verify TOTP

​Complete Warpgate authentication

​Disconnect SSH session

​Check session status

​Keep session alive

​Set sudo password

​File operations

​List directory

​Identify symlink

​Resolve path

​Read file

​Write file

​Upload file

​Download file

​Create file

​Create folder

​Delete item

​Rename item

​Move item

​Copy item

​Execute file

​Change permissions

​Extract archive

​Compress files

Build docs developers (and LLMs) love

Session management

Connect SSH session

Verify TOTP

Complete Warpgate authentication

Disconnect SSH session

Check session status

Keep session alive

Set sudo password

File operations

List directory

Identify symlink

Resolve path

Read file

Write file

Upload file

Download file

Create file

Create folder

Delete item

Rename item

Move item

Copy item

Execute file

Change permissions

Extract archive

Compress files