The protocol-based backends in this section let you mount file transfer services into the Hoody virtual filesystem. Use these endpoints to connect FTP, SFTP, SMB, WebDAV, HTTP, and HDFS servers. Each endpoint accepts a JSON configuration body and returns the new backend’s identifier, which you can then mount to a filesystem path.

Connect protocol backend

POST /api/v1/backends/ftp

Connect a new FTP backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
host	string	Yes	""	FTP host to connect to (e.g. ftp.example.com).
port	integer	No	21	FTP port number.
user	string	No	"user"	FTP username.
pass	string	No	""	FTP password.
ask_password	boolean	No	false	Allow asking for the FTP password at runtime when none is supplied.
tls	boolean	No	false	Use Implicit FTPS (FTP over TLS), usually served on port 990.
explicit_tls	boolean	No	false	Use Explicit FTPS — upgrades a plain text connection to TLS.
no_check_certificate	boolean	No	false	Skip verification of the server’s TLS certificate.
no_check_upload	boolean	No	false	Skip post-upload size/mtime verification.
disable_epsv	boolean	No	false	Disable EPSV even when the server advertises support.
disable_mlsd	boolean	No	false	Disable MLSD even when the server advertises support.
disable_utf8	boolean	No	false	Disable UTF-8 even when the server advertises support.
disable_tls13	boolean	No	false	Disable TLS 1.3 (workaround for servers with buggy TLS).
force_list_hidden	boolean	No	false	Use LIST -a to force listing of hidden files (disables MLSD).
writing_mdtm	boolean	No	false	Use MDTM to set modification time (VsFtpd quirk).
concurrency	integer	No	0	Maximum number of simultaneous FTP connections (0 = unlimited).
idle_timeout	integer	No	60	Max idle time before closing connections (seconds; 0 = indefinite).
close_timeout	integer	No	60	Max time to wait for a close response (seconds).
shut_timeout	integer	No	60	Max time to wait for data-connection close status (seconds).
tls_cache_size	integer	No	32	Size of the TLS session cache for control and data connections (0 disables).
encoding	string	No	"35749890"	Backend encoding. One of: Asterisk,Ctl,Dot,Slash, BackSlash,Ctl,Del,Dot,RightSpace,Slash,SquareBracket, Ctl,LeftPeriod,Slash.
description	string	No	""	Description of the remote.
socks_proxy	string	No	""	SOCKS5 proxy host. Format: user:pass@host:port, user@host:port, or host:port.

Response

201

{
  "data": {
    "backend_type": "ftp",
    "id": "bk_ftp_3a8c1f9d2e7b",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "FTP backend connected successfully",
  "success": true
}

400

{
  "error": "Failed to connect to FTP server: dial tcp: lookup ftp.example.com: no such host",
  "success": false
}

SDK Example

await client.files.backends.connectFtp({
  data: {
    host: "ftp.example.com",
    port: 21,
    user: "alice",
    pass: "s3cret",
    explicit_tls: true
  }
});

POST /api/v1/backends/sftp

Connect a new SSH/SFTP backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
host	string	Yes	""	SSH host to connect to (e.g. example.com).
port	integer	No	22	SSH port number.
user	string	No	"user"	SSH username.
pass	string	No	""	SSH password (leave blank to use ssh-agent).
key_file	string	No	""	Path to a PEM-encoded private key file.
key_file_pass	string	No	""	Passphrase for an encrypted PEM private key (old OpenSSH format only).
key_pem	string	No	""	Raw PEM-encoded private key, single line with \n for line breaks.
key_use_agent	boolean	No	false	Force usage of the ssh-agent.
pubkey	string	No	""	SSH public certificate for public certificate authentication.
pubkey_file	string	No	""	Path to a public key file.
ask_password	boolean	No	false	Allow prompting for the password at runtime when none is supplied.
disable_hashcheck	boolean	No	false	Disable SSH-command-based detection of remote file hashing.
disable_concurrent_reads	boolean	No	false	Disable concurrent reads.
disable_concurrent_writes	boolean	No	false	Disable concurrent writes.
copy_is_hardlink	boolean	No	false	Implement server-side copies as hardlinks.
set_modtime	boolean	No	true	Set the modified time on the remote after writing.
skip_links	boolean	No	false	Skip symlinks and other non-regular files.
use_fstat	boolean	No	false	Use fstat instead of stat to avoid exceeding server file-open limits.
use_insecure_cipher	boolean	No	false	Allow insecure ciphers/key exchange (must be false if ciphers or key_exchange is set).
concurrency	integer	No	64	Maximum outstanding requests per file.
connections	integer	No	0	Maximum simultaneous SFTP connections (0 = unlimited).
idle_timeout	integer	No	60	Max idle time before closing connections (seconds; 0 = indefinite).
chunk_size	string	No	"32768"	Upload/download chunk size in bytes (RFC limit 32768; some servers accept more).
ciphers	string	No	[]	Space-separated list of ciphers ordered by preference.
macs	string	No	[]	Space-separated list of MAC algorithms ordered by preference.
key_exchange	string	No	[]	Space-separated list of key exchange algorithms ordered by preference.
host_key_algorithms	string	No	[]	Space-separated list of host key algorithms ordered by preference.
known_hosts_file	string	No	""	Optional path to a known_hosts file to enable host key validation.
md5sum_command	string	No	""	Command used to read md5 hashes (blank = autodetect).
sha1sum_command	string	No	""	Command used to read sha1 hashes (blank = autodetect).
path_override	string	No	""	Override path used by SSH shell commands (prefix with @ to keep subpaths).
server_command	string	No	""	Path/command to start the SFTP server on the remote host.
subsystem	string	No	"sftp"	SSH2 subsystem on the remote host.
shell_type	string	No	""	Type of SSH shell on the remote server. One of: none, unix, powershell, cmd.
ssh	string	No	[]	Path and arguments to an external ssh binary.
set_env	string	No	[]	Environment variables to pass to sftp and remote commands.
socks_proxy	string	No	""	SOCKS5 proxy host. Format: user:pass@host:port, user@host:port, or host:port.
description	string	No	""	Description of the remote.

Caution

The use_insecure_cipher, ciphers, and key_exchange options are mutually exclusive in certain combinations. If you set use_insecure_cipher: true, do not set ciphers or key_exchange. Enabling insecure ciphers may allow plaintext recovery by an attacker.

Response

201

{
  "data": {
    "backend_type": "sftp",
    "id": "bk_sftp_7d2e9c4a1f0b",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "SFTP backend connected successfully",
  "success": true
}

400

{
  "error": "SSH authentication failed: handshake failed: ssh: no authentication methods available",
  "success": false
}

SDK Example

await client.files.backends.connectSftp({
  data: {
    host: "sftp.example.com",
    port: 22,
    user: "alice",
    key_file: "~/.ssh/id_ed25519",
    chunk_size: "262144"
  }
});

POST /api/v1/backends/smb

Connect a new SMB/CIFS backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
host	string	Yes	""	SMB server hostname (e.g. example.com).
port	integer	No	445	SMB port number.
user	string	No	"user"	SMB username.
pass	string	No	""	SMB password.
domain	string	No	"WORKGROUP"	Domain name for NTLM authentication.
spn	string	No	""	Service principal name. Required by some clusters.
case_insensitive	boolean	No	true	Whether the server is case-insensitive (always true on Windows shares).
hide_special_share	boolean	No	true	Hide special shares such as print$.
idle_timeout	integer	No	60	Max idle time before closing connections (seconds; 0 = indefinite).
encoding	string	No	"56698766"	Backend encoding identifier.
description	string	No	""	Description of the remote.

Response

201

{
  "data": {
    "backend_type": "smb",
    "id": "bk_smb_4f1b8a2c6d09",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "SMB backend connected successfully",
  "success": true
}

400

{
  "error": "NTLM authentication failed: invalid username or password",
  "success": false
}

SDK Example

await client.files.backends.connectSmb({
  data: {
    host: "files.example.local",
    port: 445,
    user: "alice",
    pass: "s3cret",
    domain: "EXAMPLE"
  }
});

POST /api/v1/backends/webdav

Connect a new WebDAV backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
url	string	Yes	""	URL of the WebDAV host (e.g. https://example.com).
user	string	No	""	Username. For NTLM, use the format Domain\User.
pass	string	No	""	Password.
bearer_token	string	No	""	Bearer token (e.g. a Macaroon) used instead of user/password.
bearer_token_command	string	No	""	Shell command that prints a bearer token at runtime.
vendor	string	No	""	WebDAV vendor. One of: fastmail, nextcloud, owncloud, sharepoint, sharepoint-ntlm, hoody-vfs, other.
headers	string	No	[]	Comma-separated key,value HTTP header pairs applied to every request.
unix_socket	string	No	""	Path to a Unix domain socket to dial instead of opening a TCP connection.
auth_redirect	boolean	No	false	Preserve the Authorization header across redirects.
owncloud_exclude_mounts	boolean	No	false	Exclude ownCloud-mounted storages from listings.
owncloud_exclude_shares	boolean	No	false	Exclude ownCloud shares from listings.
pacer_min_sleep	integer	No	0	Minimum sleep between API calls (seconds).
nextcloud_chunk_size	string	No	"10485760"	Nextcloud upload chunk size in bytes (0 disables chunked uploads).
encoding	string	No	""	Backend encoding.
description	string	No	""	Description of the remote.

Note

For Nextcloud, raising the server-side max chunk size to 1 GB significantly improves upload throughput. See the Nextcloud admin documentation for maxChunkSize.

Response

201

{
  "data": {
    "backend_type": "webdav",
    "id": "bk_webdav_5e2c7a8b1d34",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "WebDAV backend connected successfully",
  "success": true
}

400

{
  "error": "WebDAV PROPFIND failed: 401 Unauthorized",
  "success": false
}

SDK Example

await client.files.backends.connectWebdav({
  data: {
    url: "https://cloud.example.com/remote.php/dav/files/alice",
    user: "alice",
    pass: "s3cret",
    vendor: "nextcloud"
  }
});

POST /api/v1/backends/http

Connect a new HTTP backend (read-only mount of an HTTP/HTTPS host).

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
url	string	Yes	""	URL of the HTTP host (e.g. https://example.com). You can embed credentials as https://user:pass@example.com.
headers	string	No	[]	Comma-separated key,value HTTP headers applied to every request.
no_escape	boolean	No	false	Do not URL-escape metacharacters in path names.
no_head	boolean	No	false	Skip HEAD requests (faster listings, but no sizes/timestamps).
no_slash	boolean	No	false	Treat text/html content as directories (server doesn’t append /).
description	string	No	""	Description of the remote.

Tip

When no_slash is enabled, the backend will treat every response with Content-Type: text/html as a directory and parse links from the body. This can occasionally mistake actual HTML files for directories.

Response

201

{
  "data": {
    "backend_type": "http",
    "id": "bk_http_8c3d6f2a9e71",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "HTTP backend connected successfully",
  "success": true
}

400

{
  "error": "Invalid URL: parse \"not-a-url\": invalid URI for request",
  "success": false
}

SDK Example

await client.files.backends.connectHttp({
  data: {
    url: "https://downloads.example.com/public",
    no_head: true
  }
});

POST /api/v1/backends/hdfs

Connect a new Hadoop Distributed File System (HDFS) backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
namenode	string	Yes	[]	Hadoop name nodes and ports (e.g. namenode-1:8020,namenode-2:8020).
username	string	No	""	Hadoop user name. Allowed value: root.
service_principal_name	string	No	""	Kerberos Service Principal Name for the namenode (e.g. hdfs/namenode.hadoop.docker).
data_transfer_protection	string	No	""	Kerberos data transfer protection. Allowed value: privacy.
encoding	string	No	"50430082"	Backend encoding identifier.
description	string	No	""	Description of the remote.

Note

Set service_principal_name to enable Kerberos authentication. When Kerberos is enabled, data_transfer_protection may be set to privacy to require wire encryption between client and datanodes.

Response

201

{
  "data": {
    "backend_type": "hdfs",
    "id": "bk_hdfs_1a9b4d2e7c80",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "HDFS backend connected successfully",
  "success": true
}

400

{
  "error": "Failed to connect to namenode: dial tcp 10.0.0.5:8020: i/o timeout",
  "success": false
}

SDK Example

await client.files.backends.connectHdfs({
  data: {
    namenode: "namenode-1.hadoop.local:8020,namenode-2.hadoop.local:8020",
    username: "root",
    service_principal_name: "hdfs/namenode.hadoop.local"
  }
});