File Protocols

Connect protocol-based storage backends so Hoody can mount them as file sources. These endpoints register FTP, SFTP, SMB, WebDAV, HTTP, and HDFS remote file systems. Use them when integrating on-premise file servers, SSH-accessible hosts, web-based file collections, or Hadoop clusters.

All endpoints register a new backend and return its identifier. Mount the backend separately to expose it on a filesystem path.

FTP

POST /api/v1/backends/ftp

Register an FTP backend. Supports implicit FTPS (typically port 990) and explicit FTPS (typically port 21).

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
host	string	Yes	""	FTP host to connect to. E.g. ftp.example.com.
ask_password	boolean	No	false	Allow asking for FTP password when needed.
close_timeout	integer	No	60	Maximum time to wait for a response to close (seconds).
concurrency	integer	No	0	Maximum number of FTP simultaneous connections (0 for unlimited).
description	string	No	""	Description of the remote.
disable_epsv	boolean	No	false	Disable using EPSV even if the server advertises support.
disable_mlsd	boolean	No	false	Disable using MLSD even if the server advertises support.
disable_tls13	boolean	No	false	Disable TLS 1.3 (workaround for buggy FTP servers).
disable_utf8	boolean	No	false	Disable using UTF-8 even if the server advertises support.
encoding	string	No	"35749890"	The encoding for the backend. See the encoding section in the overview.
explicit_tls	boolean	No	false	Use Explicit FTPS (FTP over TLS). Cannot be combined with tls.
force_list_hidden	boolean	No	false	Use LIST -a to force listing of hidden files. Disables MLSD.
idle_timeout	integer	No	60	Max time before closing idle connections (seconds). 0 keeps connections indefinitely.
no_check_certificate	boolean	No	false	Do not verify the TLS certificate of the server.
no_check_upload	boolean	No	false	Don’t verify the upload is OK after writing.
pass	string	No	""	FTP password.
port	integer	No	21	FTP port number.
shut_timeout	integer	No	60	Maximum time to wait for data connection closing status (seconds).
socks_proxy	string	No	""	Socks 5 proxy host. Format: user:pass@host:port.
tls	boolean	No	false	Use Implicit FTPS (FTP over TLS). Cannot be combined with explicit_tls.
tls_cache_size	integer	No	32	Size of TLS session cache. Use 0 to disable.
user	string	No	"user"	FTP username.
writing_mdtm	boolean	No	false	Use MDTM to set modification time (VsFtpd quirk).

Caution

explicit_tls and tls cannot both be true. Explicit FTPS upgrades a plain-text connection on port 21; implicit FTPS connects over TLS from the start on port 990.

cURL

curl -X POST https://api.example.com/api/v1/backends/ftp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "ftp.example.com",
    "user": "admin",
    "pass": "s3cret",
    "port": 21,
    "explicit_tls": false
  }'

SDK

const result = await client.files.backends.connectFtp({
  host: "ftp.example.com",
  user: "admin",
  pass: "s3cret",
  port: 21,
  explicit_tls: false,
});

201 Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bkt_01HQ5F2X9P3R7Y8K",
    "type": "files",
    "backend_type": "ftp",
    "mount_paths": []
  }
}

400 Response

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

HDFS

POST /api/v1/backends/hdfs

Register a Hadoop Distributed File System backend.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
namenode	string	Yes	""	Hadoop name nodes and ports. E.g. namenode-1:8020,namenode-2:8020.
data_transfer_protection	string	No	""	Kerberos data transfer protection. Allowed value: privacy.
description	string	No	""	Description of the remote.
encoding	string	No	"50430082"	The encoding for the backend. See the encoding section in the overview.
service_principal_name	string	No	""	Kerberos service principal name for the namenode. E.g. hdfs/namenode.hadoop.docker.
username	string	No	""	Hadoop user name. Allowed value: root.

cURL

curl -X POST https://api.example.com/api/v1/backends/hdfs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "namenode": "namenode-1.hadoop.local:8020,namenode-2.hadoop.local:8020",
    "username": "hdfs"
  }'

SDK

const result = await client.files.backends.connectHdfs({
  namenode: "namenode-1.hadoop.local:8020,namenode-2.hadoop.local:8020",
  username: "hdfs",
});

201 Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bkt_01HQ5F3Z9P3R7Y8L",
    "type": "files",
    "backend_type": "hdfs",
    "mount_paths": []
  }
}

400 Response

{
  "success": false,
  "error": "Failed to connect to HDFS namenode: dial tcp: connection refused"
}

HTTP

POST /api/v1/backends/http

Register an HTTP backend for read-only access to web-based file collections.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
url	string	Yes	""	URL of the HTTP host. E.g. https://example.com, or https://user:pass@example.com for basic auth.
description	string	No	""	Description of the remote.
headers	string	No	""	Comma-separated key,value HTTP headers for all transactions. Supports standard CSV encoding.
no_escape	boolean	No	false	Do not escape URL metacharacters in path names.
no_head	boolean	No	false	Don’t use HEAD requests to discover file sizes or check existence.
no_slash	boolean	No	false	Treat text/html responses as directories (for sites without trailing /).

cURL

curl -X POST https://api.example.com/api/v1/backends/http \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/files",
    "no_head": true
  }'

SDK

const result = await client.files.backends.connectHttp({
  url: "https://example.com/files",
  no_head: true,
});

201 Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bkt_01HQ5F4A9P3R7Y8M",
    "type": "files",
    "backend_type": "http",
    "mount_paths": []
  }
}

400 Response

{
  "success": false,
  "error": "Invalid URL: parse \"https//example.com\": invalid URI for request"
}

SFTP

POST /api/v1/backends/sftp

Register an SFTP backend. Supports key-based, password, and ssh-agent authentication.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
host	string	Yes	""	SSH host to connect to. E.g. example.com.
ask_password	boolean	No	false	Allow asking for SFTP password when needed. Skips ssh-agent when true.
chunk_size	string	No	"32768"	Upload and download chunk size. RFC max is 32768; values up to 255000 work with OpenSSH.
ciphers	string	No	""	Space-separated cipher list, ordered by preference. Incompatible with use_insecure_cipher.
concurrency	integer	No	64	Maximum number of outstanding requests per file.
connections	integer	No	0	Maximum number of SFTP simultaneous connections (0 for unlimited).
copy_is_hardlink	boolean	No	false	Implement server-side copies via hardlinks.
description	string	No	""	Description of the remote.
disable_concurrent_reads	boolean	No	false	Disable concurrent reads (workaround for servers that limit file downloads).
disable_concurrent_writes	boolean	No	false	Disable concurrent writes.
disable_hashcheck	boolean	No	false	Disable execution of SSH commands for remote file hashing.
host_key_algorithms	string	No	""	Space-separated host key algorithm list, ordered by preference.
idle_timeout	integer	No	60	Max time before closing idle connections (seconds). 0 keeps connections indefinitely.
key_exchange	string	No	""	Space-separated key exchange algorithm list, ordered by preference.
key_file	string	No	""	Path to PEM-encoded private key file. Leave blank to use ssh-agent.
key_file_pass	string	No	""	Passphrase for the PEM-encoded private key file.
key_pem	string	No	""	Raw PEM-encoded private key as a single line with \n line breaks. Overrides key_file.
key_use_agent	boolean	No	false	Force usage of the ssh-agent.
known_hosts_file	string	No	""	Path to known_hosts file (e.g. ~/.ssh/known_hosts). Enables server host key validation.
macs	string	No	""	Space-separated MAC algorithm list, ordered by preference.
md5sum_command	string	No	""	Command to read MD5 hashes. Blank for autodetect.
pass	string	No	""	SSH password. Leave blank to use ssh-agent.
path_override	string	No	""	Override path used by SSH shell commands. Useful for Synology NAS boxes.
port	integer	No	22	SSH port number.
pubkey	string	No	""	SSH public certificate for public certificate-based auth. Overrides pubkey_file.
pubkey_file	string	No	""	Path to public key file for public certificate-based auth.
server_command	string	No	""	Path or command to run an SFTP server on the remote host. Ignores subsystem.
set_env	string	No	""	Space-separated VAR=value environment variables for SFTP and commands.
set_modtime	boolean	No	true	Set the modified time on the remote.
sha1sum_command	string	No	""	Command to read SHA1 hashes. Blank for autodetect.
shell_type	string	No	""	SSH shell type. Allowed values: none, unix, powershell, cmd. Blank for autodetect.
skip_links	boolean	No	false	Skip symlinks and any non-regular files.
socks_proxy	string	No	""	Socks 5 proxy host. Format: user:pass@host:port.
ssh	string	No	""	Path and arguments to an external ssh binary. Overrides internal SSH config.
subsystem	string	No	"sftp"	SSH2 subsystem on the remote host.
use_fstat	boolean	No	false	Use fstat instead of stat. Workaround for IBM Sterling SFTP servers.
use_insecure_cipher	boolean	No	false	Enable insecure ciphers (aes128-cbc, 3des-cbc, etc.). Incompatible with ciphers and key_exchange.
user	string	No	"user"	SSH username.

Danger

Setting use_insecure_cipher to true enables ciphers and key-exchange methods (including 3des-cbc) that may allow an attacker to recover plaintext data. Only enable this against trusted legacy servers.

cURL

curl -X POST https://api.example.com/api/v1/backends/sftp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "sftp.example.com",
    "user": "deploy",
    "pass": "s3cret",
    "port": 22
  }'

SDK

const result = await client.files.backends.connectSftp({
  host: "sftp.example.com",
  user: "deploy",
  pass: "s3cret",
  port: 22,
});

201 Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bkt_01HQ5F5B9P3R7Y8N",
    "type": "files",
    "backend_type": "sftp",
    "mount_paths": []
  }
}

400 Response

{
  "success": false,
  "error": "Failed to connect: ssh: handshake failed: ssh: no common algorithms"
}

SMB

POST /api/v1/backends/smb

Register an SMB / CIFS backend for Windows shares and Samba servers.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
host	string	Yes	""	SMB server hostname to connect to. E.g. example.com.
case_insensitive	boolean	No	true	Whether the server is configured to be case-insensitive. Always true on Windows shares.
description	string	No	""	Description of the remote.
domain	string	No	"WORKGROUP"	Domain name for NTLM authentication.
encoding	string	No	"56698766"	The encoding for the backend. See the encoding section in the overview.
hide_special_share	boolean	No	true	Hide special shares (e.g. print$) that users aren’t supposed to access.
idle_timeout	integer	No	60	Max time before closing idle connections (seconds). 0 keeps connections indefinitely.
pass	string	No	""	SMB password.
port	integer	No	445	SMB port number.
spn	string	No	""	Service principal name. E.g. cifs/remotehost:1020 for clusters.
user	string	No	"user"	SMB username.

cURL

curl -X POST https://api.example.com/api/v1/backends/smb \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "fileserver.example.com",
    "user": "admin",
    "pass": "s3cret",
    "domain": "CORPORATE"
  }'

SDK

const result = await client.files.backends.connectSmb({
  host: "fileserver.example.com",
  user: "admin",
  pass: "s3cret",
  domain: "CORPORATE",
});

201 Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bkt_01HQ5F6C9P3R7Y8P",
    "type": "files",
    "backend_type": "smb",
    "mount_paths": []
  }
}

400 Response

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

WebDAV

POST /api/v1/backends/webdav

Register a WebDAV backend. Supports Nextcloud, ownCloud, SharePoint, Fastmail, and generic WebDAV servers.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
url	string	Yes	""	URL of the WebDAV host. E.g. https://example.com.
auth_redirect	boolean	No	false	Preserve the Authorization header across redirects.
bearer_token	string	No	""	Bearer token instead of user/password (e.g. a Macaroon).
bearer_token_command	string	No	""	Command to run to obtain a bearer token.
description	string	No	""	Description of the remote.
encoding	string	No	""	The encoding for the backend. See the encoding section in the overview.
headers	string	No	""	Comma-separated key,value HTTP headers for all transactions. Supports standard CSV encoding.
nextcloud_chunk_size	string	No	"10485760"	Nextcloud upload chunk size (0 to disable chunked uploads).
owncloud_exclude_mounts	boolean	No	false	Exclude ownCloud mounted storages.
owncloud_exclude_shares	boolean	No	false	Exclude ownCloud shares.
pacer_min_sleep	integer	No	0	Minimum sleep between API calls (seconds).
pass	string	No	""	WebDAV password.
unix_socket	string	No	""	Path to a Unix domain socket to dial instead of opening a TCP connection.
user	string	No	""	WebDAV username. For NTLM, use the Domain\User format.
vendor	string	No	""	WebDAV vendor. Allowed values: fastmail, nextcloud, owncloud, sharepoint, sharepoint-ntlm, hoody-vfs, other.

cURL

curl -X POST https://api.example.com/api/v1/backends/webdav \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cloud.example.com/remote.php/dav",
    "user": "alice",
    "pass": "s3cret",
    "vendor": "nextcloud"
  }'

SDK

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

201 Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bkt_01HQ5F7D9P3R7Y8Q",
    "type": "files",
    "backend_type": "webdav",
    "mount_paths": []
  }
}

400 Response

{
  "success": false,
  "error": "Failed to connect: 401 Unauthorized: invalid credentials"
}