# File Protocols

**Page:** api/files/mount/protocols

[Download Raw Markdown](./api/files/mount/protocols.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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



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


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



#### SDK Example

```typescript
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. |


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



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


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



#### SDK Example

```typescript
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



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


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



#### SDK Example

```typescript
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. |


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


#### Response



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


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



#### SDK Example

```typescript
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. |


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



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


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



#### SDK Example

```typescript
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. |


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



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


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



#### SDK Example

```typescript
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"
  }
});
```