File Protocols

The endpoints on this page connect protocol-based remote backends — FTP, HDFS, HTTP, SFTP, SMB, and WebDAV — to a Hoody file container. After connecting a backend, mount it into the container’s filesystem with the mount endpoints. Each endpoint accepts a protocol-specific configuration payload and returns the new backend’s metadata, including its id and an empty mount_paths array (a backend must be mounted before it is reachable inside the container).

All endpoints return 201 Created on success and 400 Bad Request when the connection cannot be established or the payload is invalid.

FTP

Connect an FTP server as a backend. Supports plain FTP, implicit FTPS (tls: true), and explicit FTPS (explicit_tls: true).

POST /api/v1/backends/ftp

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	If set and no password is supplied, Hoody prompts for one.
tls	boolean	No	false	Use Implicit FTPS (FTP over TLS from the start), usually served on port 990. Mutually exclusive with explicit_tls.
explicit_tls	boolean	No	false	Use Explicit FTPS (upgrade a plain text connection with AUTH TLS). Mutually exclusive with tls.
no_check_certificate	boolean	No	false	Skip verification of the server’s TLS certificate.
disable_tls13	boolean	No	false	Disable TLS 1.3 (workaround for buggy FTP servers).
disable_epsv	boolean	No	false	Disable EPSV even if the server advertises support.
disable_mlsd	boolean	No	false	Disable MLSD even if the server advertises support.
disable_utf8	boolean	No	false	Disable UTF-8 even if the server advertises support.
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).
no_check_upload	boolean	No	false	Skip the post-upload size and modification-time verification.
concurrency	integer	No	0	Maximum number of FTP simultaneous connections; 0 for unlimited. Use with care — can cause deadlocks.
idle_timeout	integer	No	60	Max time before closing idle connections, in seconds. 0 to keep connections indefinitely.
close_timeout	integer	No	60	Maximum time to wait for a response to close, in seconds.
shut_timeout	integer	No	60	Maximum time to wait for the data connection closing status, in seconds.
tls_cache_size	integer	No	32	Size of the TLS session cache for control and data connections. 0 disables the cache.
socks_proxy	string	No	""	SOCKS5 proxy host. Supports user:pass@host:port, user@host:port, or host:port.
encoding	string	No	"35749890"	Backend encoding. Accepted values: Asterisk,Ctl,Dot,Slash, BackSlash,Ctl,Del,Dot,RightSpace,Slash,SquareBracket, Ctl,LeftPeriod,Slash.
description	string	No	""	Description of the remote.

cURL

curl -X POST "https://proj-demo123-cont-demo456-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/ftp" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "ftp.example.com",
    "user": "alice",
    "pass": "s3cret",
    "explicit_tls": true,
    "port": 21
  }'

SDK

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

201 Created

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

400 Bad Request

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

HDFS

Connect a Hadoop Distributed File System cluster as a backend. Supports Kerberos authentication via the service_principal_name and data_transfer_protection fields.

POST /api/v1/backends/hdfs

This endpoint takes no parameters.

Request body

Name	Type	Required	Default	Description
namenode	string	Yes	[]	Hadoop namenodes and ports (e.g. namenode-1:8020,namenode-2:8020).
username	string	No	""	Hadoop user name. Accepted value: root.
service_principal_name	string	No	""	Kerberos SPN for the namenode (e.g. hdfs/namenode.hadoop.lan). Enables KERBEROS authentication.
data_transfer_protection	string	No	""	Kerberos data transfer protection. Accepted value: privacy. Used only with KERBEROS enabled.
encoding	string	No	"50430082"	Backend encoding.
description	string	No	""	Description of the remote.

cURL

curl -X POST "https://proj-demo123-cont-demo456-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/hdfs" \
  -H "Content-Type: application/json" \
  -d '{
    "namenode": "namenode-1.hadoop.lan:8020,namenode-2.hadoop.lan:8020",
    "username": "root",
    "service_principal_name": "hdfs/namenode.hadoop.lan"
  }'

SDK

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

201 Created

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

400 Bad Request

{
  "success": false,
  "error": "Failed to connect to HDFS backend: namenode not reachable"
}

HTTP

Connect a generic HTTP server as a backend. Treats the URL as a read-only filesystem of HTTP-fetchable resources.

POST /api/v1/backends/http

This endpoint takes no parameters.

Request body

Name	Type	Required	Default	Description
url	string	Yes	""	URL of the HTTP host to connect to (e.g. https://example.com).
headers	string	No	[]	Comma-separated key,value HTTP headers applied to all transactions. CSV-encoded values are supported.
no_escape	boolean	No	false	Do not escape URL metacharacters in path names.
no_head	boolean	No	false	Don’t issue HEAD requests when listing directories. Speeds up listings but loses file sizes and times.
no_slash	boolean	No	false	The site does not end directories with /; treat Content-Type: text/html responses as directories.
description	string	No	""	Description of the remote.

cURL

curl -X POST "https://proj-demo123-cont-demo456-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/http" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://downloads.example.com/mirror",
    "headers": "\"User-Agent\",\"hoody/1.0\""
  }'

SDK

await client.files.backends.connectHttp({
  url: "https://downloads.example.com/mirror",
  headers: "\"User-Agent\",\"hoody/1.0\""
});

201 Created

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

400 Bad Request

{
  "success": false,
  "error": "Failed to connect to HTTP backend: invalid URL"
}

SFTP

Connect an SSH/SFTP server as a backend. Supports password, key file, PEM-encoded private key, and ssh-agent authentication, plus Kerberos-aware SFTP subsystems and external ssh binaries.

POST /api/v1/backends/sftp

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.
ask_password	boolean	No	false	If set and no password is supplied, Hoody prompts for one and skips the ssh-agent.
key_file	string	No	""	Path to a PEM-encoded private key file. ~ and ${RCLONE_CONFIG_DIR} are expanded. Leave blank to use ssh-agent.
key_file_pass	string	No	""	Passphrase for an old-format PEM-encrypted private key file.
key_pem	string	No	""	Raw PEM-encoded private key on a single line with \n line endings. Overrides key_file.
key_use_agent	boolean	No	false	Force the use of ssh-agent. With key_file set, only that key is requested.
pubkey_file	string	No	""	Path to the public key file (for public certificate authentication).
pubkey	string	No	""	Inline SSH public certificate. Overrides pubkey_file.
known_hosts_file	string	No	""	Path to a known_hosts file enabling server host key validation. Accepted value: ~/.ssh/known_hosts.
use_insecure_cipher	boolean	No	false	Enable insecure ciphers and key exchange methods. Must be false if ciphers or key_exchange are set.
ciphers	string	No	[]	Space-separated list of session encryption ciphers, ordered by preference.
key_exchange	string	No	[]	Space-separated list of key exchange algorithms, ordered by preference.
macs	string	No	[]	Space-separated list of MAC algorithms, ordered by preference.
host_key_algorithms	string	No	[]	Space-separated list of host key algorithms, ordered by preference.
subsystem	string	No	"sftp"	SSH2 subsystem on the remote host.
server_command	string	No	""	Path or command to run an SFTP server on the remote. Overrides subsystem.
ssh	string	No	[]	Path and arguments to an external ssh binary. Skips internal SSH configuration.
shell_type	string	No	""	Type of remote SSH shell. Accepted values: none, unix, powershell, cmd. Blank enables autodetect.
path_override	string	No	""	Override the path used by SSH shell commands (useful when SFTP and shell paths differ, e.g. Synology).
set_env	string	No	[]	Environment variables passed to the SFTP client and shell commands (VAR=value, space-separated).
set_modtime	boolean	No	true	Set the modification time on the remote after upload.
md5sum_command	string	No	""	Command used to read MD5 hashes. Blank for autodetect.
sha1sum_command	string	No	""	Command used to read SHA-1 hashes. Blank for autodetect.
chunk_size	string	No	"32768"	Upload and download SFTP protocol packet size, in bytes. Default is the RFC maximum; larger values can improve high-latency throughput.
concurrency	integer	No	64	Maximum number of outstanding requests per file. Higher values increase throughput at the cost of memory.
connections	integer	No	0	Maximum number of SFTP simultaneous connections; 0 for unlimited.
idle_timeout	integer	No	60	Max time before closing idle connections, in seconds. 0 to keep connections indefinitely.
disable_concurrent_reads	boolean	No	false	Disable concurrent reads (use when a server limits per-file downloads).
disable_concurrent_writes	boolean	No	false	Disable concurrent writes during upload.
disable_hashcheck	boolean	No	false	Disable the SSH probe that determines whether remote hashing is available.
copy_is_hardlink	boolean	No	false	Implement server-side copies as hardlinks. Requires server support.
skip_links	boolean	No	false	Skip symlinks and other non-regular files.
use_fstat	boolean	No	false	Use fstat instead of stat (works around servers that limit open files).
socks_proxy	string	No	""	SOCKS5 proxy host. Supports user:pass@host:port, user@host:port, or host:port.
description	string	No	""	Description of the remote.

cURL

curl -X POST "https://proj-demo123-cont-demo456-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/sftp" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "files.example.com",
    "user": "deploy",
    "port": 22,
    "key_file": "~/.ssh/id_ed25519",
    "key_use_agent": true,
    "known_hosts_file": "~/.ssh/known_hosts"
  }'

SDK

await client.files.backends.connectSftp({
  host: "files.example.com",
  user: "deploy",
  port: 22,
  key_file: "~/.ssh/id_ed25519",
  key_use_agent: true,
  known_hosts_file: "~/.ssh/known_hosts"
});

201 Created

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

400 Bad Request

{
  "success": false,
  "error": "Failed to connect to SFTP backend: ssh: handshake failed: knownhosts: key mismatch"
}

SMB

Connect an SMB / CIFS share as a backend. Windows shares are always case-insensitive.

POST /api/v1/backends/smb

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 (e.g. cifs/remotehost:1020) required by some clustered servers.
case_insensitive	boolean	No	true	Whether the server is case-insensitive. Always true for Windows shares.
hide_special_share	boolean	No	true	Hide special shares such as print$.
idle_timeout	integer	No	60	Max time before closing idle connections, in seconds. 0 to keep connections indefinitely.
encoding	string	No	"56698766"	Backend encoding.
description	string	No	""	Description of the remote.

cURL

curl -X POST "https://proj-demo123-cont-demo456-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/smb" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "nas.corp.example.com",
    "user": "alice",
    "pass": "s3cret",
    "domain": "CORP"
  }'

SDK

await client.files.backends.connectSmb({
  host: "nas.corp.example.com",
  user: "alice",
  pass: "s3cret",
  domain: "CORP"
});

201 Created

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

400 Bad Request

{
  "success": false,
  "error": "Failed to connect to SMB backend: NT_STATUS_LOGON_FAILURE"
}

WebDAV

Connect a WebDAV server as a backend. Includes presets for several popular WebDAV vendors.

POST /api/v1/backends/webdav

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 Domain\\User format.
pass	string	No	""	Password.
bearer_token	string	No	""	Bearer token (e.g. a Macaroon) used instead of user/pass.
bearer_token_command	string	No	""	Command that prints a bearer token to stdout.
vendor	string	No	""	WebDAV vendor preset. Accepted values: fastmail, nextcloud, owncloud, sharepoint, sharepoint-ntlm, hoody-vfs, other.
headers	string	No	[]	Comma-separated key,value HTTP headers applied to all transactions. CSV-encoded values are supported.
auth_redirect	boolean	No	false	Preserve the Authorization header across redirects (workaround for some servers).
nextcloud_chunk_size	string	No	"10485760"	Nextcloud upload chunk size, in bytes. Set to 0 to disable chunked uploading.
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, in seconds.
unix_socket	string	No	""	Path to a Unix domain socket to dial instead of opening a TCP connection.
encoding	string	No	""	Backend encoding. Defaults to identity unless vendor is sharepoint-ntlm.
description	string	No	""	Description of the remote.

cURL

curl -X POST "https://proj-demo123-cont-demo456-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/webdav" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cloud.example.com/remote.php/dav/files/alice",
    "user": "alice",
    "pass": "s3cret",
    "vendor": "nextcloud"
  }'

SDK

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

201 Created

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

400 Bad Request

{
  "success": false,
  "error": "Failed to connect to WebDAV backend: 401 Unauthorized"
}