File Protocols

Connect remote storage backends over standard file transfer and network protocols. Each endpoint registers a backend that can later be mounted to a filesystem path inside the container. Use these endpoints to integrate FTP, SFTP, SMB, HDFS, HTTP, and WebDAV sources with Hoody.

All backends accept protocol-specific options in the request body and return a backend identifier on success. Newly created backends have an empty mount_paths array — mount them with the Mounts API to expose them on a local path.

File Transfer Protocols

`POST /api/v1/backends/ftp`

Connect to an FTP or FTPS backend. Supports both implicit and explicit TLS modes via the tls and explicit_tls flags.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`host`	string	Yes	FTP host to connect to (e.g. `ftp.example.com`)
`ask_password`	boolean	No	Allow asking for FTP password when needed. Default: `false`
`close_timeout`	integer	No	Maximum time to wait for a response to close, in seconds. Default: `60`
`concurrency`	integer	No	Maximum number of FTP simultaneous connections; `0` for unlimited. Default: `0`
`description`	string	No	Description of the remote. Default: `""`
`disable_epsv`	boolean	No	Disable using EPSV even if the server advertises support. Default: `false`
`disable_mlsd`	boolean	No	Disable using MLSD even if the server advertises support. Default: `false`
`disable_tls13`	boolean	No	Disable TLS 1.3 (workaround for buggy FTP servers). Default: `false`
`disable_utf8`	boolean	No	Disable using UTF-8 even if the server advertises support. Default: `false`
`encoding`	string	No	Backend encoding. One of `Asterisk,Ctl,Dot,Slash`, `BackSlash,Ctl,Del,Dot,RightSpace,Slash,SquareBracket`, `Ctl,LeftPeriod,Slash`. Default: `"35749890"`
`explicit_tls`	boolean	No	Use Explicit FTPS. Default: `false`
`force_list_hidden`	boolean	No	Use `LIST -a` to force listing of hidden files. Disables MLSD. Default: `false`
`idle_timeout`	integer	No	Max idle time before closing connections, in seconds. Default: `60`
`no_check_certificate`	boolean	No	Skip TLS certificate verification. Default: `false`
`no_check_upload`	boolean	No	Skip post-upload verification. Default: `false`
`pass`	string	No	FTP password. Default: `""`
`port`	integer	No	FTP port number. Default: `21`
`shut_timeout`	integer	No	Maximum time to wait for data connection closing status. Default: `60`
`socks_proxy`	string	No	SOCKS5 proxy host. Default: `""`
`tls`	boolean	No	Use Implicit FTPS. Default: `false`
`tls_cache_size`	integer	No	Size of TLS session cache. Default: `32`
`user`	string	No	FTP username. Default: `user`
`writing_mdtm`	boolean	No	Use MDTM to set modification time. Default: `false`

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": "s3cret",
    "port": 21,
    "tls": false
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.connectFtp({
  host: 'ftp.example.com',
  user: 'alice',
  pass: 's3cret',
  port: 21,
  tls: false,
});

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "ftp-8c1f2a3b",
    "type": "ftp",
    "backend_type": "ftp",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "connection refused: ftp.example.com:21"
}

`POST /api/v1/backends/sftp`

Connect to an SSH/SFTP backend. Supports password, key file, and SSH agent authentication, plus a wide range of SSH cipher and key exchange options.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`host`	string	Yes	SSH host to connect to (e.g. `example.com`)
`ask_password`	boolean	No	Allow asking for SFTP password when needed. Default: `false`
`chunk_size`	string	No	Upload and download chunk size in bytes. Default: `"32768"`
`ciphers`	string	No	Space separated list of ciphers, ordered by preference. Default: `[]`
`concurrency`	integer	No	Maximum outstanding requests per file. Default: `64`
`connections`	integer	No	Maximum simultaneous SFTP connections; `0` for unlimited. Default: `0`
`copy_is_hardlink`	boolean	No	Enable server-side copies via hardlinks. Default: `false`
`description`	string	No	Description of the remote. Default: `""`
`disable_concurrent_reads`	boolean	No	Disable concurrent reads. Default: `false`
`disable_concurrent_writes`	boolean	No	Disable concurrent writes. Default: `false`
`disable_hashcheck`	boolean	No	Disable SSH hash check commands. Default: `false`
`host_key_algorithms`	string	No	Space separated list of host key algorithms. Default: `[]`
`idle_timeout`	integer	No	Max idle time before closing connections, in seconds. Default: `60`
`key_exchange`	string	No	Space separated list of key exchange algorithms. Default: `[]`
`key_file`	string	No	Path to PEM-encoded private key file. Default: `""`
`key_file_pass`	string	No	Passphrase for the PEM-encoded private key file. Default: `""`
`key_pem`	string	No	Raw PEM-encoded private key. Overrides `key_file`. Default: `""`
`key_use_agent`	boolean	No	Force usage of the SSH agent. Default: `false`
`known_hosts_file`	string	No	Path to known_hosts file. Set to `~/.ssh/known_hosts` to enable host key validation. Default: `""`
`macs`	string	No	Space separated list of MAC algorithms. Default: `[]`
`md5sum_command`	string	No	Command used to read md5 hashes. Default: `""`
`pass`	string	No	SSH password. Leave blank to use ssh-agent. Default: `""`
`path_override`	string	No	Override path used by SSH shell commands. Default: `""`
`port`	integer	No	SSH port number. Default: `22`
`pubkey`	string	No	SSH public certificate. Overrides `pubkey_file`. Default: `""`
`pubkey_file`	string	No	Path to public key file. Default: `""`
`server_command`	string	No	Path or command to run the sftp server on the remote host. Ignores `subsystem`. Default: `""`
`set_env`	string	No	Environment variables to pass to sftp and commands. Default: `[]`
`set_modtime`	boolean	No	Set the modified time on the remote. Default: `true`
`sha1sum_command`	string	No	Command used to read sha1 hashes. Default: `""`
`shell_type`	string	No	Type of SSH shell on the remote server. One of `none`, `unix`, `powershell`, `cmd`. Default: `""`
`skip_links`	boolean	No	Skip symlinks and other non-regular files. Default: `false`
`socks_proxy`	string	No	SOCKS5 proxy host. Default: `""`
`ssh`	string	No	Path and arguments to an external ssh binary. Default: `[]`
`subsystem`	string	No	SSH2 subsystem on the remote host. Default: `"sftp"`
`use_fstat`	boolean	No	Use fstat instead of stat. Default: `false`
`use_insecure_cipher`	boolean	No	Enable insecure ciphers and key exchange methods. One of `false`, `true`. Default: `false`
`user`	string	No	SSH username. Default: `user`

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": "sftp.example.com",
    "user": "deploy",
    "pass": "s3cret",
    "port": 22,
    "key_file": "/home/deploy/.ssh/id_ed25519"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.connectSftp({
  host: 'sftp.example.com',
  user: 'deploy',
  pass: 's3cret',
  port: 22,
  key_file: '/home/deploy/.ssh/id_ed25519',
});

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

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

Network File Systems

`POST /api/v1/backends/smb`

Connect to an SMB / CIFS server. Configure the Windows domain, port, and optional service principal name for Kerberos-aware clusters.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`host`	string	Yes	SMB server hostname to connect to (e.g. `example.com`)
`case_insensitive`	boolean	No	Whether the server is configured to be case-insensitive. Always `true` on Windows shares. Default: `true`
`description`	string	No	Description of the remote. Default: `""`
`domain`	string	No	Domain name for NTLM authentication. Default: `"WORKGROUP"`
`encoding`	string	No	Backend encoding. Default: `"56698766"`
`hide_special_share`	boolean	No	Hide special shares such as `print$`. Default: `true`
`idle_timeout`	integer	No	Max idle time before closing connections, in seconds. Default: `60`
`pass`	string	No	SMB password. Default: `""`
`port`	integer	No	SMB port number. Default: `445`
`spn`	string	No	Service principal name (e.g. `cifs/remotehost:1020`). Default: `""`
`user`	string	No	SMB username. Default: `user`

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.corp.example.com",
    "user": "alice",
    "pass": "s3cret",
    "domain": "CORP",
    "port": 445
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "smb-7d2e0f1a",
    "type": "smb",
    "backend_type": "smb",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "smb: logon failure: unknown user name or bad password"
}

`POST /api/v1/backends/hdfs`

Connect to a Hadoop Distributed File System backend. Configure one or more namenodes and optional Kerberos authentication settings.

This endpoint takes no parameters.

Request Body

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

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",
    "service_principal_name": "hdfs/namenode.hadoop.docker"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "hdfs-5b9c8e21",
    "type": "hdfs",
    "backend_type": "hdfs",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "dial tcp namenode-1:8020: connect: no route to host"
}

Web-Based Protocols

`POST /api/v1/backends/http`

Connect to a plain HTTP or HTTPS host for read-only access to files served by a web server.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`url`	string	Yes	URL of HTTP host to connect to (e.g. `https://example.com`). Default: `""`
`description`	string	No	Description of the remote. Default: `""`
`headers`	string	No	CSV-encoded list of HTTP headers to set on all transactions. Default: `[]`
`no_escape`	boolean	No	Do not escape URL metacharacters in path names. Default: `false`
`no_head`	boolean	No	Skip `HEAD` requests when listing directories. Default: `false`
`no_slash`	boolean	No	Site does not end directories with `/`. Treats `Content-Type: text/html` files as directories. Default: `false`

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://downloads.example.com/public",
    "description": "Public download mirror"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.connectHttp({
  url: 'https://downloads.example.com/public',
  description: 'Public download mirror',
});

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "http-4f1a8b22",
    "type": "http",
    "backend_type": "http",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "Get https://downloads.example.com/: 404 Not Found"
}

`POST /api/v1/backends/webdav`

Connect to a WebDAV server. Supports vendor-specific presets for Nextcloud, ownCloud, SharePoint, Fastmail, and Hoody VFS itself.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`url`	string	Yes	URL of HTTP host to connect to (e.g. `https://example.com`). Default: `""`
`auth_redirect`	boolean	No	Preserve authentication on HTTP redirects. Default: `false`
`bearer_token`	string	No	Bearer token instead of user/pass (e.g. a Macaroon). Default: `""`
`bearer_token_command`	string	No	Command to run to obtain a bearer token. Default: `""`
`description`	string	No	Description of the remote. Default: `""`
`encoding`	string	No	Backend encoding. Default: `""`
`headers`	string	No	CSV-encoded list of HTTP headers. Default: `[]`
`nextcloud_chunk_size`	string	No	Nextcloud upload chunk size in bytes. `0` disables chunked uploads. Default: `"10485760"`
`owncloud_exclude_mounts`	boolean	No	Exclude ownCloud mounted storages. Default: `false`
`owncloud_exclude_shares`	boolean	No	Exclude ownCloud shares. Default: `false`
`pacer_min_sleep`	integer	No	Minimum time to sleep between API calls, in seconds. Default: `0`
`pass`	string	No	Password. For NTLM, the user must use the `Domain\User` format. Default: `""`
`unix_socket`	string	No	Path to a unix domain socket to dial instead of opening a TCP connection. Default: `""`
`user`	string	No	User name. Default: `""`
`vendor`	string	No	WebDAV vendor preset. One of `fastmail`, `nextcloud`, `owncloud`, `sharepoint`, `sharepoint-ntlm`, `hoody-vfs`, `other`. Default: `""`

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/webdav",
    "user": "alice",
    "pass": "s3cret",
    "vendor": "nextcloud"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "webdav-9e3c7a5d",
    "type": "webdav",
    "backend_type": "webdav",
    "mount_paths": []
  }
}

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