# Cloud Storage

**Page:** api/files/mount/cloud

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

---

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



Connect cloud storage providers — Google Drive, Dropbox, OneDrive, iCloud, and many more — to Hoody's virtual filesystem. Each endpoint below creates a new backend connection with provider-specific configuration. Once connected, the backend can be mounted to a filesystem path.

All endpoints accept a JSON body with provider-specific configuration. Most fields are optional with sensible defaults; a small set of fields are required for authentication. All successful connections return `201 Created` with the new backend's identifier, and validation failures return `400 Bad Request`.


Most backends use OAuth and require no upfront credentials — the platform handles the OAuth dance on your behalf. The `data.id` returned by the connect endpoint is the backend identifier you'll use for subsequent operations (mounting, listing, etc.).


---

## Box

Connect a Box account. Supports both `user` and `enterprise` sub-types.

### `POST /api/v1/backends/box`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `access_token` | string | No | `""` | Box App Primary Access Token. Leave blank normally. |
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use the provider defaults. |
| `box_config_file` | string | No | `""` | Box App `config.json` location. Leave blank normally. |
| `box_sub_type` | string | No | `"user"` | One of: `user`, `enterprise`. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow (RFC 6749). |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `commit_retries` | integer | No | `100` | Max number of times to try committing a multipart file. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"52535298"` | The encoding for the backend. |
| `impersonate` | string | No | `""` | Impersonate this user ID when using a service account. |
| `list_chunk` | integer | No | `1000` | Size of listing chunk (1–1000). |
| `owned_by` | string | No | `""` | Only show items owned by the given login (email). |
| `root_folder_id` | string | No | `"0"` | Use a non-root folder as the starting point. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use the provider defaults. |
| `upload_cutoff` | string | No | `"52428800"` | Cutoff for switching to multipart upload (min 50 MiB). |

### Response



```json
{
  "data": {
    "backend_type": "box",
    "id": "bnd_8f3a2c1e4b5d6f7a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Box backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid configuration: client_id is required for enterprise sub-type",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectBox({
  box_sub_type: "user",
  description: "Marketing team Box account"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/box \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "box_sub_type": "user",
    "description": "Marketing team Box account"
  }'
```

---

## Google Drive

Connect a Google Drive account. Supports Shared Drives, service accounts, and team impersonation.

### `POST /api/v1/backends/drive`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `acknowledge_abuse` | boolean | No | `false` | Allow downloading files flagged as malware/spam. |
| `allow_import_name_change` | boolean | No | `false` | Allow filetype to change when uploading Google docs. |
| `alternate_export` | boolean | No | `false` | Deprecated: no longer needed. |
| `auth_owner_only` | boolean | No | `false` | Only consider files owned by the authenticated user. |
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `chunk_size` | string | No | `"8388608"` | Upload chunk size (power of 2, >= 256 KiB). |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | Google Application Client Id. Recommended to set your own. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `copy_shortcut_content` | boolean | No | `false` | Server-side copy shortcut contents instead of shortcuts. |
| `description` | string | No | `""` | Description of the remote. |
| `disable_http2` | boolean | No | `true` | Disable HTTP/2 for the drive backend. |
| `encoding` | string | No | `"16777216"` | The encoding for the backend. |
| `env_auth` | boolean | No | `false` | Get IAM credentials from runtime. One of: `false`, `true`. |
| `export_formats` | string | No | `"docx,xlsx,pptx,svg"` | Comma-separated preferred export formats. |
| `fast_list_bug_fix` | boolean | No | `true` | Work around a bug in Google Drive listing. |
| `formats` | string | No | `""` | Deprecated: see `export_formats`. |
| `impersonate` | string | No | `""` | Impersonate this user when using a service account. |
| `import_formats` | string | No | `""` | Comma-separated preferred upload formats for Google docs. |
| `keep_revision_forever` | boolean | No | `false` | Keep new head revision of each file forever. |
| `list_chunk` | integer | No | `1000` | Size of listing chunk (100–1000, 0 to disable). |
| `metadata_labels` | string | No | `"0"` | Read/write labels metadata. One of: `off`, `read`, `write`, `failok`, `read,write`. |
| `metadata_owner` | string | No | `"1"` | Read/write owner metadata. One of: `off`, `read`, `write`, `failok`, `read,write`. |
| `metadata_permissions` | string | No | `"0"` | Read/write permissions metadata. One of: `off`, `read`, `write`, `failok`, `read,write`. |
| `pacer_burst` | integer | No | `100` | Number of API calls allowed without sleeping. |
| `pacer_min_sleep` | integer | No | `0` | Minimum time to sleep between API calls (seconds). |
| `resource_key` | string | No | `""` | Resource key for accessing a link-shared file. |
| `root_folder_id` | string | No | `""` | ID of the root folder. Leave blank normally. |
| `scope` | string | No | `""` | Comma-separated list of scopes. One of: `drive`, `drive.readonly`, `drive.file`, `drive.appfolder`, `drive.metadata.readonly`. |
| `server_side_across_configs` | boolean | No | `false` | Allow server-side operations across different drive configs. |
| `service_account_credentials` | string | No | `""` | Service Account Credentials JSON blob. |
| `service_account_file` | string | No | `""` | Service Account Credentials JSON file path. |
| `shared_with_me` | boolean | No | `false` | Only show files shared with me. |
| `show_all_gdocs` | boolean | No | `false` | Show all Google Docs including non-exportable ones. |
| `size_as_quota` | boolean | No | `false` | Show sizes as storage quota usage, not actual size. |
| `skip_checksum_gphotos` | boolean | No | `false` | Skip checksums on Google photos and videos. |
| `skip_dangling_shortcuts` | boolean | No | `false` | Skip dangling shortcut files. |
| `skip_gdocs` | boolean | No | `false` | Skip Google documents in all listings. |
| `skip_shortcuts` | boolean | No | `false` | Skip shortcut files completely. |
| `starred_only` | boolean | No | `false` | Only show files that are starred. |
| `stop_on_download_limit` | boolean | No | `false` | Make download limit errors fatal. |
| `stop_on_upload_limit` | boolean | No | `false` | Make upload limit errors fatal. |
| `team_drive` | string | No | `""` | ID of the Shared Drive (Team Drive). |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |
| `trashed_only` | boolean | No | `false` | Only show files in the trash. |
| `upload_cutoff` | string | No | `"8388608"` | Cutoff for switching to chunked upload. |
| `use_created_date` | boolean | No | `false` | Use file created date instead of modified date. |
| `use_shared_date` | boolean | No | `false` | Use date file was shared instead of modified date. |
| `use_trash` | boolean | No | `true` | Send files to trash instead of deleting permanently. |
| `v2_download_min_size` | string | No | `"-1"` | If objects are greater, use drive v2 API to download. |

### Response



```json
{
  "data": {
    "backend_type": "drive",
    "id": "bnd_drive_3a7b9c2f8e1d4b6a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Google Drive backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid client_id format",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectDrive({
  client_id: "1234567890-abc.apps.googleusercontent.com",
  description: "Personal Google Drive",
  scope: "drive"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/drive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "1234567890-abc.apps.googleusercontent.com",
    "description": "Personal Google Drive",
    "scope": "drive"
  }'
```

---

## Dropbox

Connect a Dropbox account. Supports shared folders, team impersonation, and configurable batching.

### `POST /api/v1/backends/dropbox`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `batch_commit_timeout` | integer | No | `600` | Max time to wait for a batch to finish committing (seconds). |
| `batch_mode` | string | No | `"sync"` | Upload file batching mode (`off`, `sync`, `async`). |
| `batch_size` | integer | No | `0` | Max number of files in upload batch (&lt; 1000). |
| `batch_timeout` | integer | No | `0` | Max idle time before an upload batch is uploaded (seconds). |
| `chunk_size` | string | No | `"50331648"` | Upload chunk size (&lt; 150 MiB). |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"52469762"` | The encoding for the backend. |
| `impersonate` | string | No | `""` | Impersonate this user when using a business account. |
| `pacer_min_sleep` | integer | No | `0` | Minimum time to sleep between API calls (seconds). |
| `root_namespace` | string | No | `""` | Specify a different Dropbox namespace ID as the root. |
| `shared_files` | boolean | No | `false` | Work on individual shared files (read-only). |
| `shared_folders` | boolean | No | `false` | Work on shared folders. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |

### Response



```json
{
  "data": {
    "backend_type": "dropbox",
    "id": "bnd_dropbox_7c2e9f1a3b8d4e6f",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Dropbox backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid batch_mode: must be off, sync, or async",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectDropbox({
  batch_mode: "async",
  description: "Team Dropbox"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/dropbox \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_mode": "async",
    "description": "Team Dropbox"
  }'
```

---

## 1Fichier

Connect a 1Fichier account using an API key.

### `POST /api/v1/backends/fichier`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `api_key` | string | No | `""` | Your 1Fichier API key (from `https://1fichier.com/console/params.pl`). |
| `cdn` | boolean | No | `false` | Use CDN download links. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"52666494"` | The encoding for the backend. |
| `file_password` | string | No | `""` | Password for downloading a shared password-protected file. |
| `folder_password` | string | No | `""` | Password for listing files in a shared password-protected folder. |
| `shared_folder` | string | No | `""` | Identifier for a shared folder to download. |

### Response



```json
{
  "data": {
    "backend_type": "fichier",
    "id": "bnd_fichier_5d8a1b3c9e2f4a7b",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "1Fichier backend connected successfully",
  "success": true
}
```


```json
{
  "error": "API key is required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectFichier({
  api_key: "your-1fichier-api-key",
  cdn: true
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/fichier \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your-1fichier-api-key",
    "cdn": true
  }'
```

---

## Enterprise File Fabric

Connect an Enterprise File Fabric (Storage Made Easy) instance.

### `POST /api/v1/backends/filefabric`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50429954"` | The encoding for the backend. |
| `permanent_token` | string | No | `""` | Permanent Authentication Token from the File Fabric dashboard. |
| `root_folder_id` | string | No | `""` | ID of the root folder. Leave blank normally. |
| `token` | string | No | `""` | Session token (managed automatically; do not set). |
| `token_expiry` | string | No | `""` | Token expiry time (managed automatically; do not set). |
| `url` | string | **Yes** | `""` | URL of the Enterprise File Fabric. One of: `https://storagemadeeasy.com`, `https://eu.storagemadeeasy.com`, `https://yourfabric.smestorage.com`. |
| `version` | string | No | `""` | Version read from the File Fabric (managed automatically). |

### Response



```json
{
  "data": {
    "backend_type": "filefabric",
    "id": "bnd_filefabric_4e1c8a2b7f3d9e5c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Enterprise File Fabric backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Field 'url' is required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectFilefabric({
  url: "https://storagemadeeasy.com",
  permanent_token: "your-permanent-token"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/filefabric \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://storagemadeeasy.com",
    "permanent_token": "your-permanent-token"
  }'
```

---

## Files.com

Connect a Files.com account. Supports API key, username/password, or site-based authentication.

### `POST /api/v1/backends/filescom`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `api_key` | string | No | `""` | The API key used to authenticate with Files.com. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"60923906"` | The encoding for the backend. |
| `password` | string | No | `""` | The password used to authenticate with Files.com. |
| `site` | string | No | `""` | Your site subdomain (e.g. `mysite`) or custom domain. |
| `username` | string | No | `""` | The username used to authenticate with Files.com. |

### Response



```json
{
  "data": {
    "backend_type": "filescom",
    "id": "bnd_filescom_2b7e4d9c1a5f8e3b",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Files.com backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Authentication failed: invalid credentials",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectFilescom({
  site: "mysite",
  username: "alice",
  api_key: "your-files-com-api-key"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/filescom \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "mysite",
    "username": "alice",
    "api_key": "your-files-com-api-key"
  }'
```

---

## Gofile

Connect a Gofile account using an access token.

### `POST /api/v1/backends/gofile`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `access_token` | string | No | `""` | API access token from the Gofile web control panel. |
| `account_id` | string | No | `""` | Account ID. Filled in automatically; leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"323331982"` | The encoding for the backend. |
| `list_chunk` | integer | No | `1000` | Number of items to list per call. |
| `root_folder_id` | string | No | `""` | ID of the root folder. Filled in automatically; leave blank normally. |

### Response



```json
{
  "data": {
    "backend_type": "gofile",
    "id": "bnd_gofile_9f4c2a1e8b3d6e7a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Gofile backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid access token",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectGofile({
  access_token: "your-gofile-access-token"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/gofile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "your-gofile-access-token"
  }'
```

---

## Google Photos

Connect a Google Photos library. Supports read-only mode and proxy-based full-resolution downloads.

### `POST /api/v1/backends/google-photos`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `batch_commit_timeout` | integer | No | `600` | Max time to wait for a batch to finish committing (seconds). |
| `batch_mode` | string | No | `"sync"` | Upload file batching mode (`off`, `sync`, `async`). |
| `batch_size` | integer | No | `0` | Max number of files in upload batch (&lt; 50). |
| `batch_timeout` | integer | No | `0` | Max idle time before an upload batch is uploaded (seconds). |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50348034"` | The encoding for the backend. |
| `include_archived` | boolean | No | `false` | View and download archived media. |
| `proxy` | string | No | `""` | Use the `gphotosdl` proxy URL for full-resolution images. |
| `read_only` | boolean | No | `false` | Request read-only access to your photos. |
| `read_size` | boolean | No | `false` | Read the size of media items (recommended for VFS mounts). |
| `start_year` | integer | No | `2000` | Limit downloads to media uploaded after this year. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |

### Response



```json
{
  "data": {
    "backend_type": "google photos",
    "id": "bnd_gphotos_1a8b3c5d7e2f4a9b",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Google Photos backend connected successfully",
  "success": true
}
```


```json
{
  "error": "start_year must be a valid year",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectGooglePhotos({
  read_only: true,
  start_year: 2020,
  description: "Family photo library"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/google-photos \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "read_only": true,
    "start_year": 2020,
    "description": "Family photo library"
  }'
```

---

## HiDrive

Connect a HiDrive (Strato) account.

### `POST /api/v1/backends/hidrive`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `chunk_size` | string | No | `"50331648"` | Chunk size for chunked uploads (&lt; 2 GiB). |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `disable_fetching_member_count` | boolean | No | `false` | Skip fetching object counts in directories. |
| `encoding` | string | No | `"33554434"` | The encoding for the backend. |
| `endpoint` | string | No | `"https://api.hidrive.strato.com/2.1"` | API endpoint URL. |
| `root_prefix` | string | No | `"/"` | Root/parent folder for all paths. One of: `/`, `root`, `` (empty). |
| `scope_access` | string | No | `"rw"` | Access permissions. One of: `rw`, `ro`. |
| `scope_role` | string | No | `"user"` | User-level. One of: `user`, `admin`, `owner`. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |
| `upload_concurrency` | integer | No | `4` | Concurrency for chunked uploads. |
| `upload_cutoff` | string | No | `"100663296"` | Threshold for chunked uploads (&lt; 2 GiB). |

### Response



```json
{
  "data": {
    "backend_type": "hidrive",
    "id": "bnd_hidrive_6c3f8a2e9b1d4e7c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "HiDrive backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid endpoint URL",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectHidrive({
  scope_access: "rw",
  upload_concurrency: 8
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/hidrive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_access": "rw",
    "upload_concurrency": 8
  }'
```

---

## iCloud Drive

Connect an iCloud Drive account using Apple ID credentials. **Required:** Apple ID and password.

### `POST /api/v1/backends/iclouddrive`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `apple_id` | string | **Yes** | `""` | Apple ID. |
| `client_id` | string | No | `"d39ba9916b7251055b22c7f910e2ea796ee65e98b2ddecea8f5dde8d9d1a815d"` | Client id. |
| `cookies` | string | No | `""` | Cookies (internal use only). |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50438146"` | The encoding for the backend. |
| `password` | string | **Yes** | `""` | Apple ID password. |
| `trust_token` | string | No | `""` | Trust token (internal use). |


Apple may require two-factor authentication. If so, you will need to provide a trust token obtained from a trusted device. Plain password authentication may not always succeed.


### Response



```json
{
  "data": {
    "backend_type": "iclouddrive",
    "id": "bnd_icloud_3e7b2c9f4a8d1e5b",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "iCloud Drive backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Two-factor authentication required; provide trust_token",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectIclouddrive({
  apple_id: "alice@icloud.com",
  password: "app-specific-password",
  description: "Personal iCloud"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/iclouddrive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "apple_id": "alice@icloud.com",
    "password": "app-specific-password",
    "description": "Personal iCloud"
  }'
```

---

## Jottacloud

Connect a Jottacloud account.

### `POST /api/v1/backends/jottacloud`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50431886"` | The encoding for the backend. |
| `hard_delete` | boolean | No | `false` | Delete files permanently instead of moving to trash. |
| `md5_memory_limit` | string | No | `"10485760"` | Files larger than this are cached on disk for MD5. |
| `no_versions` | boolean | No | `false` | Avoid server-side versioning by recreating files. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |
| `trashed_only` | boolean | No | `false` | Only show files in the trash. |
| `upload_resume_limit` | string | No | `"10485760"` | Files larger than this can be resumed on upload failure. |

### Response



```json
{
  "data": {
    "backend_type": "jottacloud",
    "id": "bnd_jotta_8a2d5c1e9b3f7a4d",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Jottacloud backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Authentication failed",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectJottacloud({
  hard_delete: false
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/jottacloud \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hard_delete": false
  }'
```

---

## Koofr

Connect a Koofr, Digi Storage, or other Koofr-compatible storage provider. **Required:** endpoint URL, username, and password.

### `POST /api/v1/backends/koofr`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50438146"` | The encoding for the backend. |
| `endpoint` | string | **Yes** | `""` | The Koofr API endpoint. |
| `mountid` | string | No | `""` | Mount ID. If omitted, the primary mount is used. |
| `password` | string | **Yes** | `""` | Hoody-VFS password (generate one in your service settings). |
| `provider` | string | No | `""` | Storage provider. One of: `koofr`, `digistorage`, `other`. |
| `setmtime` | boolean | No | `true` | Whether the backend supports setting modification time. |
| `user` | string | **Yes** | `""` | Your user name. |

### Response



```json
{
  "data": {
    "backend_type": "koofr",
    "id": "bnd_koofr_4f1a8e2c5b9d3a7e",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Koofr backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Field 'endpoint' is required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectKoofr({
  endpoint: "https://app.koofr.net",
  user: "alice",
  password: "hoody-app-password",
  provider: "koofr"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/koofr \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://app.koofr.net",
    "user": "alice",
    "password": "hoody-app-password",
    "provider": "koofr"
  }'
```

---

## Linkbox

Connect a Linkbox account. **Required:** API token from the Linkbox account page.

### `POST /api/v1/backends/linkbox`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `description` | string | No | `""` | Description of the remote. |
| `token` | string | **Yes** | `""` | Token from `https://www.linkbox.to/admin/account`. |

### Response



```json
{
  "data": {
    "backend_type": "linkbox",
    "id": "bnd_linkbox_2c8e5a1b9f3d4c7a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Linkbox backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Field 'token' is required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectLinkbox({
  token: "your-linkbox-token"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/linkbox \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "your-linkbox-token"
  }'
```

---

## Mail.ru Cloud

Connect a Mail.ru Cloud account. **Required:** username (email) and an app password. **An app password is required** — the regular account password will not work.

### `POST /api/v1/backends/mailru`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `check_hash` | boolean | No | `true` | What to do if file checksum is mismatched or invalid. One of: `true`, `false`. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50440078"` | The encoding for the backend. |
| `pass` | string | **Yes** | `""` | App password. |
| `quirks` | string | No | `""` | Comma-separated list of internal maintenance flags (advanced). |
| `speedup_enable` | boolean | No | `true` | Skip full upload if a file with the same hash already exists. One of: `true`, `false`. |
| `speedup_file_patterns` | string | No | `"*.mkv,*.avi,*.mp4,*.mp3,*.zip,*.gz,*.rar,*.pdf"` | Comma-separated patterns eligible for hash-based upload. One of: `` (empty), `*`, `*.mkv,*.avi,*.mp4,*.mp3`, `*.zip,*.gz,*.rar,*.pdf`. |
| `speedup_max_disk` | string | No | `"3221225472"` | Max disk usage for speedup. One of: `0`, `1G`, `3G`. |
| `speedup_max_memory` | string | No | `"33554432"` | Files larger than this are always hashed on disk. One of: `0`, `32M`, `256M`. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |
| `user` | string | **Yes** | `""` | User name (usually email). |
| `user_agent` | string | No | `""` | HTTP user agent used internally by the client. |

### Response



```json
{
  "data": {
    "backend_type": "mailru",
    "id": "bnd_mailru_7d2a4c1b9e5f3a8c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Mail.ru Cloud backend connected successfully",
  "success": true
}
```


```json
{
  "error": "App password is required (not your account password)",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectMailru({
  user: "alice@mail.ru",
  pass: "app-password",
  speedup_enable: true
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/mailru \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "alice@mail.ru",
    "pass": "app-password",
    "speedup_enable": true
  }'
```

---

## Mega

Connect a Mega account. **Required:** Mega username and password.

### `POST /api/v1/backends/mega`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `debug` | boolean | No | `false` | Output more debug from Mega. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50331650"` | The encoding for the backend. |
| `hard_delete` | boolean | No | `false` | Permanently delete files instead of trashing them. |
| `pass` | string | **Yes** | `""` | Mega password. |
| `use_https` | boolean | No | `false` | Use HTTPS for transfers (useful when an ISP throttles HTTP). |
| `user` | string | **Yes** | `""` | Mega user name. |

### Response



```json
{
  "data": {
    "backend_type": "mega",
    "id": "bnd_mega_5a8c1e4b7d2f9a3e",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Mega backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid Mega credentials",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectMega({
  user: "alice@example.com",
  pass: "mega-password",
  use_https: true
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/mega \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "alice@example.com",
    "pass": "mega-password",
    "use_https": true
  }'
```

---

## Microsoft OneDrive

Connect a Microsoft OneDrive account. Supports personal, business, and SharePoint document libraries. Use the `region` field for national clouds (US gov, Germany, China).

### `POST /api/v1/backends/onedrive`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `access_scopes` | string | No | `["Files.Read","Files.ReadWrite","Files.Read.All","Files.ReadWrite.All","Sites.Read.All","offline_access"]` | Space-separated scopes to request. One of: `Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All Sites.Read.All offline_access`, `Files.Read Files.Read.All Sites.Read.All offline_access`, `Files.Read Files.ReadWrite Files.Read.All Files.ReadWrite.All offline_access`. |
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `av_override` | boolean | No | `false` | Allow download of files the server thinks has a virus. |
| `chunk_size` | string | No | `"10485760"` | Chunk size for uploads (multiple of 320 KiB, &lt;= 250 MiB). |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `delta` | boolean | No | `false` | Use delta listing for recursive listings. |
| `description` | string | No | `""` | Description of the remote. |
| `disable_site_permission` | boolean | No | `false` | Disable the request for `Sites.Read.All` permission. |
| `drive_id` | string | No | `""` | The ID of the drive to use. |
| `drive_type` | string | No | `""` | The type of the drive (`personal`, `business`, or `documentLibrary`). |
| `encoding` | string | No | `"57386894"` | The encoding for the backend. |
| `expose_onenote_files` | boolean | No | `false` | Make OneNote files show up in directory listings. |
| `hard_delete` | boolean | No | `false` | Permanently delete files on removal. |
| `hash_type` | string | No | `"auto"` | Hash type in use. One of: `auto`, `quickxor`, `sha1`, `sha256`, `crc32`, `none`. |
| `link_password` | string | No | `""` | Password for links created by the link command (paid personal accounts). |
| `link_scope` | string | No | `"anonymous"` | Scope of created links. One of: `anonymous`, `organization`. |
| `link_type` | string | No | `"view"` | Type of created links. One of: `view`, `edit`, `embed`. |
| `list_chunk` | integer | No | `1000` | Size of listing chunk. |
| `metadata_permissions` | string | No | `"0"` | Read/write permissions metadata. One of: `off`, `read`, `write`, `read,write`, `failok`. |
| `no_versions` | boolean | No | `false` | Remove all versions on modifying operations. |
| `region` | string | No | `"global"` | National cloud region. One of: `global`, `us`, `de`, `cn`. |
| `root_folder_id` | string | No | `""` | ID of the root folder. Leave blank normally. |
| `server_side_across_configs` | boolean | No | `false` | Allow server-side operations across different OneDrive configs. |
| `tenant` | string | No | `""` | Tenant ID (for client credential flow). |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |

### Response



```json
{
  "data": {
    "backend_type": "onedrive",
    "id": "bnd_onedrive_9b3d7e1a4c8f2b5d",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "OneDrive backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid region: must be one of global, us, de, cn",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectOnedrive({
  region: "global",
  drive_type: "personal",
  description: "Personal OneDrive"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/onedrive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "global",
    "drive_type": "personal",
    "description": "Personal OneDrive"
  }'
```

---

## OpenDrive

Connect an OpenDrive account. **Required:** username and password.

### `POST /api/v1/backends/opendrive`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `chunk_size` | string | No | `"10485760"` | Files will be uploaded in chunks of this size. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"62007182"` | The encoding for the backend. |
| `password` | string | **Yes** | `""` | OpenDrive password. |
| `username` | string | **Yes** | `""` | OpenDrive username. |

### Response



```json
{
  "data": {
    "backend_type": "opendrive",
    "id": "bnd_opendrive_1f5c8a2d4b7e3a9c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "OpenDrive backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Fields 'username' and 'password' are required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectOpendrive({
  username: "alice",
  password: "opendrive-password"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/opendrive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "opendrive-password"
  }'
```

---

## Pcloud

Connect a Pcloud account. Supports EU and US regions.

### `POST /api/v1/backends/pcloud`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50438146"` | The encoding for the backend. |
| `hostname` | string | No | `"api.pcloud.com"` | Hostname to connect to. One of: `api.pcloud.com`, `eapi.pcloud.com`. |
| `password` | string | No | `""` | Your Pcloud password. |
| `root_folder_id` | string | No | `"d0"` | Use a non-root folder as the starting point. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |
| `username` | string | No | `""` | Your Pcloud username (only required for the cleanup command). |

### Response



```json
{
  "data": {
    "backend_type": "pcloud",
    "id": "bnd_pcloud_3c7a9e2b1d5f8c4a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Pcloud backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid hostname",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectPcloud({
  hostname: "api.pcloud.com",
  root_folder_id: "d0"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/pcloud \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "api.pcloud.com",
    "root_folder_id": "d0"
  }'
```

---

## PikPak

Connect a PikPak account. **Required:** PikPak username and password.

### `POST /api/v1/backends/pikpak`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `chunk_size` | string | No | `"5242880"` | Chunk size for multipart uploads. |
| `description` | string | No | `""` | Description of the remote. |
| `device_id` | string | No | `""` | Device ID used for authorization. |
| `encoding` | string | No | `"56829838"` | The encoding for the backend. |
| `hash_memory_limit` | string | No | `"10485760"` | Files larger than this are cached on disk for hashing. |
| `no_media_link` | boolean | No | `false` | Use original file links instead of media links. |
| `pass` | string | **Yes** | `""` | PikPak password. |
| `root_folder_id` | string | No | `""` | ID of the root folder. Leave blank normally. |
| `trashed_only` | boolean | No | `false` | Only show files in the trash. |
| `upload_concurrency` | integer | No | `5` | Concurrency for multipart uploads. |
| `use_trash` | boolean | No | `true` | Send files to trash instead of permanently deleting. |
| `user` | string | **Yes** | `""` | PikPak username. |
| `user_agent` | string | No | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:129.0) Gecko/20100101 Firefox/129.0"` | HTTP user agent for PikPak. |

### Response



```json
{
  "data": {
    "backend_type": "pikpak",
    "id": "bnd_pikpak_6e2c4a8b1f9d3e5a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "PikPak backend connected successfully",
  "success": true
}
```


```json
{
  "error": "PikPak authentication failed",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectPikpak({
  user: "alice@example.com",
  pass: "pikpak-password",
  upload_concurrency: 4
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/pikpak \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "alice@example.com",
    "pass": "pikpak-password",
    "upload_concurrency": 4
  }'
```

---

## Pixeldrain Filesystem

Connect a Pixeldrain account. **Required:** `api_url` (use the default unless testing against a custom instance).

### `POST /api/v1/backends/pixeldrain`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `api_key` | string | No | `""` | API key for your Pixeldrain account (from `https://pixeldrain.com/user/api_keys`). |
| `api_url` | string | **Yes** | `"https://pixeldrain.com/api"` | The API endpoint to connect to. |
| `description` | string | No | `""` | Description of the remote. |
| `root_folder_id` | string | No | `"me"` | Root of the filesystem. Use `me` for your personal filesystem, or a shared directory ID. |

### Response



```json
{
  "data": {
    "backend_type": "pixeldrain",
    "id": "bnd_pixeldrain_8a4f1c2e7b9d3a5f",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Pixeldrain backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Field 'api_url' is required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectPixeldrain({
  api_url: "https://pixeldrain.com/api",
  api_key: "your-pixeldrain-api-key",
  root_folder_id: "me"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/pixeldrain \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "api_url": "https://pixeldrain.com/api",
    "api_key": "your-pixeldrain-api-key",
    "root_folder_id": "me"
  }'
```

---

## premiumize.me

Connect a premiumize.me account.

### `POST /api/v1/backends/premiumizeme`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `api_key` | string | No | `""` | API key (not normally used — use OAuth instead). |
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50438154"` | The encoding for the backend. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |

### Response



```json
{
  "data": {
    "backend_type": "premiumizeme",
    "id": "bnd_premiumizeme_2d5a8c1b9e3f4a7c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "premiumize.me backend connected successfully",
  "success": true
}
```


```json
{
  "error": "OAuth flow required to obtain a token",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectPremiumizeme({});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/premiumizeme \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

## Proton Drive

Connect a Proton Drive account. **Required:** username and password. Supports two-factor authentication and mailbox passwords for accounts that use separate login and mailbox passwords.

### `POST /api/v1/backends/protondrive`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `2fa` | string | No | `""` | The 2FA code (e.g. `000000`). |
| `app_version` | string | No | `"macos-drive@1.0.0-alpha.1+hoody-vfs"` | App version string sent with API requests. |
| `client_access_token` | string | No | `""` | Client access token key (internal use only). |
| `client_refresh_token` | string | No | `""` | Client refresh token key (internal use only). |
| `client_salted_key_pass` | string | No | `""` | Client salted key pass (internal use only). |
| `client_uid` | string | No | `""` | Client uid (internal use only). |
| `description` | string | No | `""` | Description of the remote. |
| `enable_caching` | boolean | No | `true` | Cache files and folders metadata to reduce API calls. |
| `encoding` | string | No | `"52559874"` | The encoding for the backend. |
| `mailbox_password` | string | No | `""` | Mailbox password (for two-password Proton accounts). |
| `original_file_size` | boolean | No | `true` | Return the file size before encryption. |
| `password` | string | **Yes** | `""` | The password of your Proton account. |
| `replace_existing_draft` | boolean | No | `false` | Create a new revision when filename conflict is detected. |
| `username` | string | **Yes** | `""` | The username of your Proton account. |


If you are using Proton Drive as a VFS mount, disable `enable_caching`. The current implementation does not refresh the cache when there are external changes, which will cause stale data.


### Response



```json
{
  "data": {
    "backend_type": "protondrive",
    "id": "bnd_protondrive_4b9e3a7c2f1d5e8a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Proton Drive backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Two-factor authentication required; provide '2fa'",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectProtondrive({
  username: "alice@proton.me",
  password: "login-password",
  mailbox_password: "mailbox-password",
  enable_caching: false
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/protondrive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice@proton.me",
    "password": "login-password",
    "mailbox_password": "mailbox-password",
    "enable_caching": false
  }'
```

---

## Put.io

Connect a Put.io account.

### `POST /api/v1/backends/putio`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50438146"` | The encoding for the backend. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |

### Response



```json
{
  "data": {
    "backend_type": "putio",
    "id": "bnd_putio_5f1c8a3b9e2d4c7a",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Put.io backend connected successfully",
  "success": true
}
```


```json
{
  "error": "OAuth flow required to obtain a token",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectPutio({});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/putio \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

## Quatrix by Maytech

Connect a Quatrix (by Maytech) account. **Required:** API key and host.

### `POST /api/v1/backends/quatrix`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `api_key` | string | **Yes** | `""` | API key for accessing the Quatrix account. |
| `description` | string | No | `""` | Description of the remote. |
| `effective_upload_time` | string | No | `"4s"` | Wanted upload time for one chunk. |
| `encoding` | string | No | `"50438146"` | The encoding for the backend. |
| `hard_delete` | boolean | No | `false` | Delete files permanently rather than trashing. |
| `host` | string | **Yes** | `""` | Host name of the Quatrix account. |
| `maximal_summary_chunk_size` | string | No | `"100000000"` | The maximal summary for all chunks (should be >= `transfers * minimal_chunk_size`). |
| `minimal_chunk_size` | string | No | `"10000000"` | The minimal size for one chunk. |
| `skip_project_folders` | boolean | No | `false` | Skip project folders in operations. |

### Response



```json
{
  "data": {
    "backend_type": "quatrix",
    "id": "bnd_quatrix_7a4c2e9b1d3f8a5c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Quatrix backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Fields 'api_key' and 'host' are required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectQuatrix({
  host: "acme.quatrix.io",
  api_key: "your-quatrix-api-key"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/quatrix \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "acme.quatrix.io",
    "api_key": "your-quatrix-api-key"
  }'
```

---

## Seafile

Connect a Seafile server. **Required:** `url` and `user`. Supports 2FA and encrypted libraries.

### `POST /api/v1/backends/seafile`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `2fa` | boolean | No | `false` | `true` if the account has 2FA enabled. |
| `auth_token` | string | No | `""` | Authentication token. |
| `create_library` | boolean | No | `false` | Create a library if it doesn't exist. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"16850954"` | The encoding for the backend. |
| `library` | string | No | `""` | Name of the library. Leave blank to access all non-encrypted libraries. |
| `library_key` | string | No | `""` | Library password (for encrypted libraries only). |
| `pass` | string | No | `""` | Seafile password. |
| `url` | string | **Yes** | `""` | URL of the Seafile host. One of: `https://cloud.seafile.com/`. |
| `user` | string | **Yes** | `""` | User name (usually email). |

### Response



```json
{
  "data": {
    "backend_type": "seafile",
    "id": "bnd_seafile_3f8b1c4a2e7d9a5c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Seafile backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Fields 'url' and 'user' are required",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectSeafile({
  url: "https://cloud.seafile.com/",
  user: "alice@example.com",
  pass: "seafile-password",
  library: "Documents"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/seafile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://cloud.seafile.com/",
    "user": "alice@example.com",
    "pass": "seafile-password",
    "library": "Documents"
  }'
```

---

## Citrix Sharefile

Connect a Citrix Sharefile account. Use the `root_folder_id` field to target a specific folder (e.g. `favorites`, `allshared`).

### `POST /api/v1/backends/sharefile`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `chunk_size` | string | No | `"67108864"` | Upload chunk size (power of 2, >= 256 KiB). |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"57091982"` | The encoding for the backend. |
| `endpoint` | string | No | `""` | Endpoint for API calls (e.g. `https://XXX.sharefile.com`). |
| `root_folder_id` | string | No | `""` | ID of the root folder. One of: `` (empty, personal folders), `favorites`, `allshared`, `connectors`, `top`. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |
| `upload_cutoff` | string | No | `"134217728"` | Cutoff for switching to multipart upload. |

### Response



```json
{
  "data": {
    "backend_type": "sharefile",
    "id": "bnd_sharefile_9c1a4e7b2d5f8a3c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Citrix Sharefile backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid root_folder_id value",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectSharefile({
  root_folder_id: "favorites"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/sharefile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "root_folder_id": "favorites"
  }'
```

---

## Sugarsync

Connect a Sugarsync account. Most authentication fields are managed automatically after the first OAuth handshake.

### `POST /api/v1/backends/sugarsync`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `access_key_id` | string | No | `""` | Sugarsync Access Key ID. Leave blank to use Hoody's. |
| `app_id` | string | No | `""` | Sugarsync App ID. Leave blank to use Hoody's. |
| `authorization` | string | No | `""` | Sugarsync authorization (managed automatically). |
| `authorization_expiry` | string | No | `""` | Sugarsync authorization expiry (managed automatically). |
| `deleted_id` | string | No | `""` | Sugarsync deleted folder id (managed automatically). |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50397186"` | The encoding for the backend. |
| `hard_delete` | boolean | No | `false` | Permanently delete files instead of using the deleted files folder. |
| `private_access_key` | string | No | `""` | Sugarsync Private Access Key. Leave blank to use Hoody's. |
| `refresh_token` | string | No | `""` | Sugarsync refresh token (managed automatically). |
| `root_id` | string | No | `""` | Sugarsync root id (managed automatically). |
| `user` | string | No | `""` | Sugarsync user (managed automatically). |

### Response



```json
{
  "data": {
    "backend_type": "sugarsync",
    "id": "bnd_sugarsync_6d3a8c1b4e7f2a9d",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Sugarsync backend connected successfully",
  "success": true
}
```


```json
{
  "error": "OAuth flow required to populate credentials",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectSugarsync({});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/sugarsync \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

## Uloz.to

Connect a Uloz.to account.

### `POST /api/v1/backends/ulozto`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `app_token` | string | No | `""` | Uloz.to app API key (from the API doc or customer service). |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50438146"` | The encoding for the backend. |
| `list_page_size` | integer | No | `500` | The size of a single page for list commands (1–500). |
| `password` | string | No | `""` | The password for the user. |
| `root_folder_slug` | string | No | `""` | Folder slug to use as the root for all operations. |
| `username` | string | No | `""` | The username of the principal to operate as. |

### Response



```json
{
  "data": {
    "backend_type": "ulozto",
    "id": "bnd_ulozto_1c9a4e7b2d5f8a3c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Uloz.to backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid list_page_size: must be 1-500",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectUlozto({
  username: "alice",
  password: "ulozto-password",
  app_token: "uloz-app-token",
  list_page_size: 250
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/ulozto \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "ulozto-password",
    "app_token": "uloz-app-token",
    "list_page_size": 250
  }'
```

---

## Uptobox

Connect an Uptobox account using an access token from your Uptobox account page.

### `POST /api/v1/backends/uptobox`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `access_token` | string | No | `""` | Your Uptobox access token (from `https://uptobox.com/my_account`). |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50561070"` | The encoding for the backend. |
| `private` | boolean | No | `false` | Make uploaded files private. |

### Response



```json
{
  "data": {
    "backend_type": "uptobox",
    "id": "bnd_uptobox_2e7b4c9a1d3f8a5c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Uptobox backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid access token",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectUptobox({
  access_token: "your-uptobox-token",
  private: false
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/uptobox \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "access_token": "your-uptobox-token",
    "private": false
  }'
```

---

## Yandex Disk

Connect a Yandex Disk account.

### `POST /api/v1/backends/yandex`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50429954"` | The encoding for the backend. |
| `hard_delete` | boolean | No | `false` | Delete files permanently rather than moving to trash. |
| `spoof_ua` | boolean | No | `true` | Set the user agent to match an official Yandex Disk client. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |

### Response



```json
{
  "data": {
    "backend_type": "yandex",
    "id": "bnd_yandex_8b2d5c1e7a9f3a4c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Yandex Disk backend connected successfully",
  "success": true
}
```


```json
{
  "error": "OAuth flow required to obtain a token",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectYandex({
  hard_delete: false,
  spoof_ua: true
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/yandex \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "hard_delete": false,
    "spoof_ua": true
  }'
```

---

## Zoho

Connect a Zoho WorkDrive account. Use the `region` field to target the correct Zoho region for your organization.

### `POST /api/v1/backends/zoho`

This endpoint takes no parameters.

### Request Body

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `auth_url` | string | No | `""` | Auth server URL. Leave blank to use provider defaults. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth Client Id. Leave blank normally. |
| `client_secret` | string | No | `""` | OAuth Client Secret. Leave blank normally. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"16875520"` | The encoding for the backend. |
| `region` | string | No | `""` | Zoho region. One of: `com`, `eu`, `in`, `jp`, `com.cn`, `com.au`. |
| `token` | string | No | `""` | OAuth Access Token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL. Leave blank to use provider defaults. |
| `upload_cutoff` | string | No | `"10485760"` | Cutoff for switching to large file upload API (min 10 MiB). |

### Response



```json
{
  "data": {
    "backend_type": "zoho",
    "id": "bnd_zoho_4a8c1e3b7d2f9a5c",
    "mount_paths": [],
    "type": "backend"
  },
  "message": "Zoho backend connected successfully",
  "success": true
}
```


```json
{
  "error": "Invalid region: must be one of com, eu, in, jp, com.cn, com.au",
  "success": false
}
```



### SDK

```typescript
await client.files.backends.connectZoho({
  region: "com"
});
```

### cURL

```bash
curl -X POST https://api.hoody.com/api/v1/backends/zoho \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "com"
  }'
```