Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

File protocols

Section titled “File protocols”

Connect a remote storage service over FTP, HDFS, HTTP, SFTP, SMB, or WebDAV. The remote is proved by listing its root before the backend is saved. Once a backend is connected, mount it under a filesystem path so the remote is reachable at a path inside the kit.

FTP

Section titled “FTP”

Connect an FTP backend. Supports plain FTP, implicit FTPS (TLS from the start, usually port 990), and explicit FTPS (start plain then upgrade to TLS, port 21).

POST /api/v1/backends/ftp

Section titled “POST /api/v1/backends/ftp”

Connect an FTP backend.

This endpoint takes no path, query, or header parameters.

Request body

Section titled “Request body”

A JSON object with the FTP connection settings.

NameTypeRequiredDefaultDescription
hoststringYes""FTP host to connect to, e.g. ftp.example.com.
userstringNouserFTP username.
passstringNo""FTP password.
portintegerNo21FTP port number.
tlsbooleanNofalseUse implicit FTPS (TLS from the start; usually port 990). Cannot be combined with explicit FTPS.
explicit_tlsbooleanNofalseUse explicit FTPS (upgrade an existing plain connection to TLS). Cannot be combined with implicit FTPS.
tls_cache_sizeintegerNo32TLS session cache size for control and data connections. Use 0 to disable.
allow_insecure_tls_ciphersbooleanNofalseAllow insecure TLS ciphers such as TLS_RSA_WITH_AES_128_GCM_SHA256 in addition to the secure defaults.
disable_epsvbooleanNofalseDo not use EPSV even if the server advertises support.
disable_mlsdbooleanNofalseDo not use MLSD even if the server advertises support.
disable_utf8booleanNofalseDo not use UTF-8 even if the server advertises support.
disable_tls13booleanNofalseDisable TLS 1.3 (workaround for buggy FTP servers).
force_list_hiddenbooleanNofalseUse LIST -a to force listing of hidden files. Disables MLSD.
no_check_uploadbooleanNofalseSkip the post-upload check of size and modification time. Pair with --inplace for write-only folders.
writing_mdtmbooleanNofalseUse MDTM to set modification time (VsFtpd quirk).
ask_passwordbooleanNofalseAsk for an FTP password when one is not supplied.
encodingstringNo35749890File-name encoding. Allowed values: Asterisk,Ctl,Dot,Slash, BackSlash,Ctl,Del,Dot,RightSpace,Slash,SquareBracket, Ctl,LeftPeriod,Slash.
descriptionstringNo""Description of the remote.
concurrencyintegerNo0Maximum simultaneous FTP connections; 0 is unlimited. Setting this risks deadlocks.
close_timeoutintegerNo60Seconds to wait for a response to close.
idle_timeoutintegerNo60Seconds before idle connections in the pool are closed. 0 keeps them indefinitely.
shut_timeoutintegerNo60Seconds to wait for the data connection closing status.
http_proxystringNo""HTTP CONNECT proxy URL, e.g. http://proxy.example.com:8000.
socks_proxystringNo""SOCKS5 proxy, e.g. user:pass@localhost:9005.

Response

Section titled “Response”

The credentials were proved by listing the remote’s root. A connect of an already-saved backend with the same credentials is treated as a reconnect and returns the same id.

{
  "success": true,
  "message": "Backend connected",
  "data": {
    "id": "a1b2c3d4e5f60718",
    "type": "ftp",
    "vfs_backend_type": "ftp",
    "config": {
      "host": "ftp.example.com",
      "port": 21,
      "user": "alice"
    },
    "mount_paths": []
  }
}
FieldTypeRequiredDescription
successbooleanYesWhether the request succeeded.
messagestringYesShort human-readable summary.
dataobjectYesThe connected backend.
data.idstringYesBackend id (16 hex characters).
data.typestringYesThe protocol type, as the request path named it.
data.vfs_backend_typestringYesThe Hoody backend that runs this protocol.
data.configobjectYesThe configuration as sent, with secrets hidden. A plain value (not an object or array) of host, port, user, username, region, endpoint, provider, bucket, or path is echoed; every other value is replaced by "***".
data.mount_pathsarrayYesFilesystem paths where this backend is mounted. Empty for newly connected backends.

Example

Section titled “Example”
Terminal window
curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/ftp \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "ftp.example.com",
    "user": "alice",
    "pass": "secret",
    "port": 21,
    "tls": false
  }'

HDFS

Section titled “HDFS”

Connect a Hadoop Distributed File System backend. List one or more name nodes as host:port,host:port.

POST /api/v1/backends/hdfs

Section titled “POST /api/v1/backends/hdfs”

Connect an HDFS backend.

This endpoint takes no path, query, or header parameters.

Request body

Section titled “Request body”

A JSON object with the HDFS connection settings.

NameTypeRequiredDefaultDescription
namenodestringYes""Comma-separated list of name nodes and ports, e.g. namenode-1:8020,namenode-2:8020.
usernamestringNo""Hadoop user name. Allowed value: root.
data_transfer_protectionstringNo""Kerberos data transfer protection. Allowed value: privacy. Used only with Kerberos enabled.
encodingstringNo50430082File-name encoding for the backend.
descriptionstringNo""Description of the remote.

Response

Section titled “Response”

The credentials were proved by listing the remote’s root. A connect of an already-saved backend with the same credentials is treated as a reconnect and returns the same id.

{
  "success": true,
  "message": "Backend connected",
  "data": {
    "id": "a1b2c3d4e5f60718",
    "type": "hdfs",
    "vfs_backend_type": "hdfs",
    "config": {
      "namenode": "namenode-1:8020"
    },
    "mount_paths": []
  }
}
FieldTypeRequiredDescription
successbooleanYesWhether the request succeeded.
messagestringYesShort human-readable summary.
dataobjectYesThe connected backend.
data.idstringYesBackend id (16 hex characters).
data.typestringYesThe protocol type, as the request path named it.
data.vfs_backend_typestringYesThe Hoody backend that runs this protocol.
data.configobjectYesThe configuration as sent, with secrets hidden. A plain value (not an object or array) of host, port, user, username, region, endpoint, provider, bucket, or path is echoed; every other value is replaced by "***".
data.mount_pathsarrayYesFilesystem paths where this backend is mounted. Empty for newly connected backends.

Example

Section titled “Example”
Terminal window
curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/hdfs \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namenode": "namenode-1:8020,namenode-2:8020",
    "username": "root"
  }'

HTTP

Section titled “HTTP”

Connect an HTTP or HTTPS backend. Lists the remote URL; useful for read-only mirrors, public file shares, and CDNs.

POST /api/v1/backends/http

Section titled “POST /api/v1/backends/http”

Connect an HTTP backend.

This endpoint takes no path, query, or header parameters.

Request body

Section titled “Request body”

A JSON object with the HTTP connection settings.

NameTypeRequiredDefaultDescription
urlstringYes""URL of the HTTP host to connect to, e.g. https://example.com.
headersstringNo""Comma-separated list of header key, value pairs (CSV encoded). For example 'Cookie,name=value' or '"Cookie","name=value"'. Sent only to the host in url; redirects to a different host do not receive them.
no_escapebooleanNofalseDo not escape URL metacharacters in path names.
no_headbooleanNofalseDo not use HEAD requests when listing directories (faster listings but missing sizes and unreliable file presence).
no_slashbooleanNofalseTreat text/html responses as directories. Use when the site does not append / to directories.
descriptionstringNo""Description of the remote.

Response

Section titled “Response”

The credentials were proved by listing the remote’s root. A connect of an already-saved backend with the same credentials is treated as a reconnect and returns the same id.

{
  "success": true,
  "message": "Backend connected",
  "data": {
    "id": "a1b2c3d4e5f60718",
    "type": "http",
    "vfs_backend_type": "http",
    "config": {
      "url": "https://example.com"
    },
    "mount_paths": []
  }
}
FieldTypeRequiredDescription
successbooleanYesWhether the request succeeded.
messagestringYesShort human-readable summary.
dataobjectYesThe connected backend.
data.idstringYesBackend id (16 hex characters).
data.typestringYesThe protocol type, as the request path named it.
data.vfs_backend_typestringYesThe Hoody backend that runs this protocol.
data.configobjectYesThe configuration as sent, with secrets hidden. A plain value (not an object or array) of host, port, user, username, region, endpoint, provider, bucket, or path is echoed; every other value is replaced by "***".
data.mount_pathsarrayYesFilesystem paths where this backend is mounted. Empty for newly connected backends.

Example

Section titled “Example”
Terminal window
curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/http \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "no_head": false
  }'

SFTP

Section titled “SFTP”

Connect an SSH/SFTP backend. The schema requires host and user. The description recommends supplying one of pass, password, key_pem, or key as the credential. Server-stored credentials (a key file or an ssh-agent) cannot be used.

POST /api/v1/backends/sftp

Section titled “POST /api/v1/backends/sftp”

Connect an SFTP backend.

This endpoint takes no path, query, or header parameters.

Request body

Section titled “Request body”

A JSON object with the SFTP connection settings.

NameTypeRequiredDefaultDescription
hoststringYes""SSH host, e.g. example.com.
userstringYesuserSSH username.
passstringNo""SSH password. Leave blank to use ssh-agent.
passwordstringNo(unset)Alias for pass. An empty value is ignored; if it differs from a non-empty pass, the request is rejected with 400.
key_pemstringNo""Raw PEM-encoded private key, with line endings as \n. Overrides key_file.
keystringNo(unset)Alias for key_pem. An empty value is ignored; if it differs from a non-empty key_pem, the request is rejected with 400.
key_file_passstringNo""Passphrase for an encrypted PEM private key file (old OpenSSH format).
passphrasestringNo(unset)Alias for key_file_pass. An empty value is ignored; if it differs from a non-empty key_file_pass, the request is rejected with 400.
portintegerNo22SSH port number.
subsystemstringNosftpSSH2 subsystem on the remote host.
chunk_sizestringNo32768SFTP payload size in bytes. The RFC default is 32768; larger values such as 262144 can improve throughput on high-latency links but require server support.
concurrencyintegerNo64Maximum outstanding requests for one file. Higher values raise throughput on high-latency links at the cost of memory.
connectionsintegerNo0Maximum simultaneous SFTP connections; 0 is unlimited. Setting this risks deadlocks.
copy_is_hardlinkbooleanNofalseImplement server-side copies via hardlinks. Not all servers support this.
set_modtimebooleanNotrueSet the modification time on the remote after a transfer.
disable_concurrent_readsbooleanNofalseDisable concurrent reads. Enable on servers that limit repeated downloads.
disable_concurrent_writesbooleanNofalseDisable concurrent writes.
disable_hashcheckbooleanNofalseDisable the SSH command used to probe remote hashing support.
skip_linksbooleanNofalseOmit symlinks and other non-regular files from directory listings.
use_fstatbooleanNofalseUse fstat instead of stat on open file handles. Helps servers that limit open files (for example IBM Sterling SFTP).
pin_host_keybooleanNofalsePin the server host key on first connect (Trust On First Use). Run once with this flag; the key is then written into host_keys.
host_keysstringNo""Pinned host keys as comma-separated "algo base64-key" entries (matching fields 2 and 3 of an OpenSSH known_hosts line). At most 16 entries.
host_key_algorithmsstringNo""Space-separated, ordered list of host key algorithms, e.g. ssh-ed25519 ssh-rsa ssh-dss.
ciphersstringNo""Space-separated, ordered list of session ciphers. Must not be set when use_insecure_cipher is true.
key_exchangestringNo""Space-separated, ordered list of key exchange algorithms. Must not be set when use_insecure_cipher is true.
macsstringNo""Space-separated, ordered list of MAC algorithms, e.g. umac-64-etm@openssh.com hmac-sha2-256-etm@openssh.com.
use_insecure_cipherbooleanNofalseAllow insecure ciphers and key exchange methods (aes128-cbc, aes192-cbc, aes256-cbc, 3des-cbc, diffie-hellman-group-exchange-sha256, diffie-hellman-group-exchange-sha1). Must be false when ciphers or key_exchange is set.
hashesstringNo""Comma-separated list of supported checksum types.
pubkeystringNo""SSH public certificate for public certificate-based authentication. Overrides pubkey_file.
set_envstringNo""Environment variables for the SFTP client and remote commands, e.g. VAR=value.
path_overridestringNo""Override path used by SSH shell commands. Prefix with @ to leave the path relative to the remote root. Useful for Synology NAS where SFTP and shell paths differ.
shell_typestringNo""SSH shell type. Leave blank for autodetect. Allowed values: none, unix, powershell, cmd.
ask_passwordbooleanNofalseAsk for an SFTP password when none is supplied; the ssh-agent is not contacted when this is set.
http_proxystringNo""HTTP CONNECT proxy URL, e.g. http://proxy.example.com:8000.
socks_proxystringNo""SOCKS5 proxy, e.g. user:pass@localhost:9005.
idle_timeoutintegerNo60Seconds before idle connections are closed. 0 keeps them indefinitely.
encodingstringNo33652738File-name encoding for the backend.
descriptionstringNo""Description of the remote.

Response

Section titled “Response”

The credentials were proved by listing the remote’s root. A connect of an already-saved backend with the same credentials is treated as a reconnect and returns the same id.

{
  "success": true,
  "message": "Backend connected",
  "data": {
    "id": "a1b2c3d4e5f60718",
    "type": "sftp",
    "vfs_backend_type": "sftp",
    "config": {
      "host": "example.com",
      "port": 22,
      "user": "alice"
    },
    "mount_paths": []
  }
}
FieldTypeRequiredDescription
successbooleanYesWhether the request succeeded.
messagestringYesShort human-readable summary.
dataobjectYesThe connected backend.
data.idstringYesBackend id (16 hex characters).
data.typestringYesThe protocol type, as the request path named it.
data.vfs_backend_typestringYesThe Hoody backend that runs this protocol.
data.configobjectYesThe configuration as sent, with secrets hidden. A plain value (not an object or array) of host, port, user, username, region, endpoint, provider, bucket, or path is echoed; every other value is replaced by "***".
data.mount_pathsarrayYesFilesystem paths where this backend is mounted. Empty for newly connected backends.

Example

Section titled “Example”
Terminal window
curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/sftp \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "example.com",
    "user": "alice",
    "pass": "secret",
    "port": 22
  }'

SMB

Section titled “SMB”

Connect an SMB / CIFS share. Set use_kerberos to true to authenticate with Kerberos instead of NTLM (requires a configured Kerberos credentials cache).

POST /api/v1/backends/smb

Section titled “POST /api/v1/backends/smb”

Connect an SMB backend.

This endpoint takes no path, query, or header parameters.

Request body

Section titled “Request body”

A JSON object with the SMB connection settings.

NameTypeRequiredDefaultDescription
hoststringYes""SMB server hostname, e.g. example.com.
userstringNouserSMB username.
passstringNo""SMB password.
domainstringNoWORKGROUPDomain name for NTLM authentication.
spnstringNo""Service principal name presented to the server, e.g. cifs/remotehost:1020. Often required for clusters.
portintegerNo445SMB port number.
case_insensitivebooleanNotrueWhether the server treats file names case-insensitively. Always true on Windows shares.
hide_special_sharebooleanNotrueHide administrative and other special shares (e.g. print$).
use_kerberosbooleanNofalseAuthenticate with Kerberos instead of NTLM. Requires a configured Kerberos credentials cache.
idle_timeoutintegerNo60Seconds before idle connections are closed. 0 keeps them indefinitely.
encodingstringNo56698766File-name encoding for the backend.
descriptionstringNo""Description of the remote.

Response

Section titled “Response”

The credentials were proved by listing the remote’s root. A connect of an already-saved backend with the same credentials is treated as a reconnect and returns the same id.

{
  "success": true,
  "message": "Backend connected",
  "data": {
    "id": "a1b2c3d4e5f60718",
    "type": "smb",
    "vfs_backend_type": "smb",
    "config": {
      "host": "files.example.com",
      "port": 445,
      "user": "alice"
    },
    "mount_paths": []
  }
}
FieldTypeRequiredDescription
successbooleanYesWhether the request succeeded.
messagestringYesShort human-readable summary.
dataobjectYesThe connected backend.
data.idstringYesBackend id (16 hex characters).
data.typestringYesThe protocol type, as the request path named it.
data.vfs_backend_typestringYesThe Hoody backend that runs this protocol.
data.configobjectYesThe configuration as sent, with secrets hidden. A plain value (not an object or array) of host, port, user, username, region, endpoint, provider, bucket, or path is echoed; every other value is replaced by "***".
data.mount_pathsarrayYesFilesystem paths where this backend is mounted. Empty for newly connected backends.

Example

Section titled “Example”
Terminal window
curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/smb \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "files.example.com",
    "user": "alice",
    "pass": "secret",
    "domain": "WORKGROUP",
    "port": 445
  }'

WebDAV

Section titled “WebDAV”

Connect a WebDAV backend. Set vendor to the matching software (Nextcloud, ownCloud, SharePoint, and so on) for the best listing behaviour.

POST /api/v1/backends/webdav

Section titled “POST /api/v1/backends/webdav”

Connect a WebDAV backend.

This endpoint takes no path, query, or header parameters.

Request body

Section titled “Request body”

A JSON object with the WebDAV connection settings.

NameTypeRequiredDefaultDescription
urlstringYes""URL of the WebDAV host, e.g. https://example.com.
userstringNo""User name. For NTLM, use the Domain\User format.
passstringNo""Password.
bearer_tokenstringNo""Bearer token (for example a Macaroon) instead of user and password.
vendorstringNo""WebDAV site, service, or software. Allowed values: fastmail, nextcloud, owncloud, infinitescale, sharepoint, sharepoint-ntlm, hoody-vfs, other.
auth_redirectbooleanNofalseKeep the Authorization header across redirects. Required by some servers, but exposes credentials on HTTPS to HTTP redirects.
headersstringNo""Comma-separated list of header key, value pairs (CSV encoded), e.g. 'Cookie,name=value'.
nextcloud_chunk_sizestringNo10485760Nextcloud upload chunk size in bytes. 0 disables chunked uploads.
owncloud_exclude_mountsbooleanNofalseExclude ownCloud mounted storages from listings.
owncloud_exclude_sharesbooleanNofalseExclude ownCloud shares from listings.
pacer_min_sleepintegerNo0Minimum seconds to wait between API calls.
encodingstringNo""File-name encoding for the backend. Default is Slash,LtGt,DoubleQuote,Colon,Question,Asterisk,Pipe,Hash,Percent,BackSlash,Del,Ctl,LeftSpace,LeftTilde,RightSpace,RightPeriod,InvalidUtf8 for sharepoint-ntlm and identity otherwise.
descriptionstringNo""Description of the remote.

Response

Section titled “Response”

The credentials were proved by listing the remote’s root. A connect of an already-saved backend with the same credentials is treated as a reconnect and returns the same id.

{
  "success": true,
  "message": "Backend connected",
  "data": {
    "id": "a1b2c3d4e5f60718",
    "type": "webdav",
    "vfs_backend_type": "webdav",
    "config": {
      "url": "https://cloud.example.com/remote.php/dav",
      "user": "alice"
    },
    "mount_paths": []
  }
}
FieldTypeRequiredDescription
successbooleanYesWhether the request succeeded.
messagestringYesShort human-readable summary.
dataobjectYesThe connected backend.
data.idstringYesBackend id (16 hex characters).
data.typestringYesThe protocol type, as the request path named it.
data.vfs_backend_typestringYesThe Hoody backend that runs this protocol.
data.configobjectYesThe configuration as sent, with secrets hidden. A plain value (not an object or array) of host, port, user, username, region, endpoint, provider, bucket, or path is echoed; every other value is replaced by "***".
data.mount_pathsarrayYesFilesystem paths where this backend is mounted. Empty for newly connected backends.

Example

Section titled “Example”
Terminal window
curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/webdav \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cloud.example.com/remote.php/dav",
    "user": "alice",
    "pass": "secret",
    "vendor": "nextcloud"
  }'