# Object Storage

**Page:** api/files/mount/object

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

---

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



Object Storage backends let you mount remote storage systems — cloud object stores, S3-compatible providers, OpenStack Swift, and decentralized networks — as filesystems inside Hoody. Each provider has a dedicated `POST /api/v1/backends/{provider}` endpoint that accepts a provider-specific configuration object. On success, the API returns a backend identifier and the empty `mount_paths` array; the backend can then be mounted to a filesystem path. All endpoints return `201` on success and `400` on connection failure.


All endpoints on this page accept the configuration object directly in the request body. They take no path, query, or header parameters.


## Cloud Object Storage

### `POST /api/v1/backends/azureblob`

Microsoft Azure Blob Storage. Supports multiple authentication methods (account key, SAS, service principal, managed identity, Azure CLI) and configurable access tiers (hot, cool, cold, archive).

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `access_tier` | string | No | `""` | Access tier for blobs: `hot`, `cool`, `cold`, or `archive`. Leave blank to use the account default. |
| `account` | string | No | `""` | Azure Storage Account Name. Required unless using SAS URL or Emulator. |
| `archive_tier_delete` | boolean | No | `false` | Delete archive tier blobs before overwriting (required because archive blobs cannot be updated in place). |
| `chunk_size` | string | No | `"4194304"` | Upload chunk size in bytes. |
| `client_certificate_password` | string | No | `""` | Password for the certificate file (service principal with certificate). |
| `client_certificate_path` | string | No | `""` | Path to a PEM or PKCS12 certificate file. |
| `client_id` | string | No | `""` | Client ID for service principal or user authentication. |
| `client_secret` | string | No | `""` | Service principal client secret. |
| `client_send_certificate_chain` | boolean | No | `false` | Send the x5c certificate chain header on certificate-based auth. |
| `delete_snapshots` | string | No | `""` | How to deal with snapshots on blob deletion. One of `""`, `"include"`, `"only"`. |
| `description` | string | No | `""` | Description of the remote. |
| `directory_markers` | boolean | No | `false` | Upload empty objects ending in `/` to persist empty folders. |
| `disable_checksum` | boolean | No | `false` | Skip MD5 checksum calculation before upload. |
| `disable_instance_discovery` | boolean | No | `false` | Skip Microsoft Entra instance metadata lookup (use for disconnected clouds). |
| `encoding` | string | No | `"21078018"` | Backend encoding. |
| `endpoint` | string | No | `""` | Endpoint for the service. Leave blank normally. |
| `env_auth` | boolean | No | `false` | Read credentials from environment variables, CLI, or MSI. |
| `key` | string | No | `""` | Storage Account Shared Key. Leave blank to use SAS URL or Emulator. |
| `list_chunk` | integer | No | `5000` | Maximum number of blobs per listing request. |
| `memory_pool_flush_time` | integer | No | `60` | Internal memory buffer pool flush time in seconds (deprecated). |
| `memory_pool_use_mmap` | boolean | No | `false` | Use mmap buffers in internal memory pool (deprecated). |
| `msi_client_id` | string | No | `""` | Client ID of the user-assigned MSI. |
| `msi_mi_res_id` | string | No | `""` | Azure resource ID of the user-assigned MSI. |
| `msi_object_id` | string | No | `""` | Object ID of the user-assigned MSI. |
| `no_check_container` | boolean | No | `false` | Don't check or create the container. |
| `no_head_object` | boolean | No | `false` | Skip HEAD before GET on object reads. |
| `password` | string | No | `""` | User password (user/password auth). |
| `public_access` | string | No | `""` | Public access level for the container. One of `""`, `"blob"`, `"container"`. |
| `sas_url` | string | No | `""` | SAS URL for container-level access. |
| `service_principal_file` | string | No | `""` | Path to a service principal credentials JSON file. |
| `tenant` | string | No | `""` | Service principal tenant ID. |
| `upload_concurrency` | integer | No | `16` | Number of chunks uploaded concurrently per file. |
| `upload_cutoff` | string | No | `""` | Cutoff for switching to chunked upload (deprecated). |
| `use_az` | boolean | No | `false` | Authenticate using the Azure CLI `az` tool. |
| `use_emulator` | boolean | No | `false` | Use the local Azure Storage Emulator. |
| `use_msi` | boolean | No | `false` | Use a managed service identity to authenticate. |
| `username` | string | No | `""` | Username (usually an email) for user/password auth. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/azureblob \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "mystorageaccount",
    "key": "EXAMPLEKEY==",
    "description": "Production blob storage"
  }'
```


```js
await client.files.backends.connectAzureblob({
  account: "mystorageaccount",
  key: "EXAMPLEKEY==",
  description: "Production blob storage"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_8a7b9c0d1e2f3a4b",
    "backend_type": "azureblob",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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



### `POST /api/v1/backends/azurefiles`

Microsoft Azure Files. SMB-compatible file shares with the same authentication options as Azure Blob.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `account` | string | No | `""` | Azure Storage Account Name. |
| `chunk_size` | string | No | `"4194304"` | Upload chunk size in bytes. |
| `client_certificate_password` | string | No | `""` | Password for the certificate file. |
| `client_certificate_path` | string | No | `""` | Path to a PEM or PKCS12 certificate file. |
| `client_id` | string | No | `""` | Client ID for service principal or user authentication. |
| `client_secret` | string | No | `""` | Service principal client secret. |
| `client_send_certificate_chain` | boolean | No | `false` | Send the x5c certificate chain header. |
| `connection_string` | string | No | `""` | Azure Files connection string. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"54634382"` | Backend encoding. |
| `endpoint` | string | No | `""` | Endpoint for the service. |
| `env_auth` | boolean | No | `false` | Read credentials from the environment. |
| `key` | string | No | `""` | Storage Account Shared Key. |
| `max_stream_size` | string | No | `"10737418240"` | Max size for streamed files (10 GiB). |
| `msi_client_id` | string | No | `""` | Client ID of the user-assigned MSI. |
| `msi_mi_res_id` | string | No | `""` | Azure resource ID of the user-assigned MSI. |
| `msi_object_id` | string | No | `""` | Object ID of the user-assigned MSI. |
| `password` | string | No | `""` | User password for user/password auth. |
| `sas_url` | string | No | `""` | SAS URL. |
| `service_principal_file` | string | No | `""` | Path to a service principal credentials JSON file. |
| `share_name` | string | No | `""` | Azure Files share name (required to access the share). |
| `tenant` | string | No | `""` | Service principal tenant ID. |
| `upload_concurrency` | integer | No | `16` | Number of chunks uploaded concurrently per file. |
| `use_msi` | boolean | No | `false` | Use a managed service identity to authenticate. |
| `username` | string | No | `""` | Username for user/password auth. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/azurefiles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "mystorageaccount",
    "share_name": "myshare",
    "key": "EXAMPLEKEY=="
  }'
```


```js
await client.files.backends.connectAzurefiles({
  account: "mystorageaccount",
  share_name: "myshare",
  key: "EXAMPLEKEY=="
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_2c4d6e8f0a1b3c5d",
    "backend_type": "azurefiles",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


```json
{
  "success": false,
  "error": "Could not access share 'myshare' on account 'mystorageaccount'"
}
```



### `POST /api/v1/backends/google-cloud-storage`

Google Cloud Storage. Supports service account credentials, OAuth, and anonymous public-bucket access. This is **not** Google Drive.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `access_token` | string | No | `""` | Short-lived access token. |
| `anonymous` | boolean | No | `false` | Access public buckets and objects without credentials. |
| `auth_url` | string | No | `""` | Auth server URL override. |
| `bucket_acl` | string | No | `""` | ACL for new buckets. One of `authenticatedRead`, `private`, `projectPrivate`, `publicRead`, `publicReadWrite`. |
| `bucket_policy_only` | boolean | No | `false` | Use bucket-level IAM policies only. |
| `client_credentials` | boolean | No | `false` | Use OAuth2 client credentials flow. |
| `client_id` | string | No | `""` | OAuth client ID. |
| `client_secret` | string | No | `""` | OAuth client secret. |
| `decompress` | boolean | No | `false` | Decompress gzip-encoded objects on download. |
| `description` | string | No | `""` | Description of the remote. |
| `directory_markers` | boolean | No | `false` | Persist empty folders with marker objects. |
| `encoding` | string | No | `"50348034"` | Backend encoding. |
| `endpoint` | string | No | `""` | Endpoint for the service. |
| `env_auth` | boolean | No | `false` | Get IAM credentials from the environment. |
| `location` | string | No | `""` | Location for newly created buckets. One of the supported GCS regions (e.g. `us`, `eu`, `asia`, `us-central1`, `europe-west1`, etc.). |
| `no_check_bucket` | boolean | No | `false` | Skip checking or creating the bucket. |
| `object_acl` | string | No | `""` | ACL for new objects. One of `authenticatedRead`, `bucketOwnerFullControl`, `bucketOwnerRead`, `private`, `projectPrivate`, `publicRead`. |
| `project_number` | string | No | `""` | GCP project number (for bucket list/create/delete). |
| `service_account_credentials` | string | No | `""` | Service account credentials JSON blob. |
| `service_account_file` | string | No | `""` | Path to a service account credentials JSON file. |
| `storage_class` | string | No | `""` | Storage class for new objects. One of `""`, `MULTI_REGIONAL`, `REGIONAL`, `NEARLINE`, `COLDLINE`, `ARCHIVE`, `DURABLE_REDUCED_AVAILABILITY`. |
| `token` | string | No | `""` | OAuth access token as a JSON blob. |
| `token_url` | string | No | `""` | Token server URL override. |
| `user_project` | string | No | `""` | User project (for requester-pays buckets). |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/google-cloud-storage \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_file": "/etc/hoody/gcs-sa.json",
    "project_number": "123456789012",
    "location": "us-central1"
  }'
```


```js
await client.files.backends.connectGoogleCloudStorage({
  service_account_file: "/etc/hoody/gcs-sa.json",
  project_number: "123456789012",
  location: "us-central1"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_5e6f7a8b9c0d1e2f",
    "backend_type": "google cloud storage",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


```json
{
  "success": false,
  "error": "Failed to load service account credentials from /etc/hoody/gcs-sa.json"
}
```



### `POST /api/v1/backends/oracleobjectstorage`

Oracle Cloud Infrastructure Object Storage. Supports instance principals, user principals, workload identity, and resource principals.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `attempt_resume_upload` | boolean | No | `false` | Attempt to resume previously started multipart uploads. |
| `chunk_size` | string | No | `"5242880"` | Upload chunk size in bytes. |
| `compartment` | string | No | `""` | Compartment OCID (required only to list buckets). |
| `config_file` | string | No | `"~/.oci/config"` | Path to the OCI config file. |
| `config_profile` | string | No | `"Default"` | Profile name inside the OCI config file. |
| `copy_cutoff` | string | No | `"4999610368"` | Cutoff (in bytes) for switching to multipart copy. |
| `copy_timeout` | integer | No | `60` | Timeout for async copy operations in seconds. |
| `description` | string | No | `""` | Description of the remote. |
| `disable_checksum` | boolean | No | `false` | Skip MD5 checksum calculation before upload. |
| `encoding` | string | No | `"50331650"` | Backend encoding. |
| `endpoint` | string | No | `""` | Object storage API endpoint. |
| `leave_parts_on_error` | boolean | No | `false` | Leave successfully uploaded parts on error for manual recovery. |
| `max_upload_parts` | integer | No | `10000` | Maximum number of parts in a multipart upload. |
| `namespace` | string | **Yes** | `""` | Object storage namespace. |
| `no_check_bucket` | boolean | No | `false` | Skip checking or creating the bucket. |
| `provider` | string | **Yes** | `"env_auth"` | Authentication provider. One of `env_auth`, `user_principal_auth`, `instance_principal_auth`, `workload_identity_auth`, `resource_principal_auth`, `no_auth`. |
| `region` | string | **Yes** | `""` | Object storage region. |
| `sse_customer_algorithm` | string | No | `""` | SSE-C algorithm. One of `""`, `AES256`. |
| `sse_customer_key` | string | No | `""` | SSE-C base64-encoded 256-bit key. |
| `sse_customer_key_file` | string | No | `""` | Path to a file containing the SSE-C key. |
| `sse_customer_key_sha256` | string | No | `""` | Base64-encoded SHA256 hash of the SSE-C key. |
| `sse_kms_key_id` | string | No | `""` | OCID of a KMS master encryption key. |
| `storage_tier` | string | No | `"Standard"` | Storage class. One of `Standard`, `InfrequentAccess`, `Archive`. |
| `upload_concurrency` | integer | No | `10` | Number of chunks uploaded concurrently per file. |
| `upload_cutoff` | string | No | `"209715200"` | Cutoff (in bytes) for switching to chunked upload. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/oracleobjectstorage \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "user_principal_auth",
    "namespace": "id3nxb4ktwxa",
    "region": "us-phoenix-1",
    "compartment": "ocid1.compartment.oc1..aaaaaaaabcdefghijk"
  }'
```


```js
await client.files.backends.connectOracleobjectstorage({
  provider: "user_principal_auth",
  namespace: "id3nxb4ktwxa",
  region: "us-phoenix-1",
  compartment: "ocid1.compartment.oc1..aaaaaaaabcdefghijk"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_1a2b3c4d5e6f7a8b",
    "backend_type": "oracleobjectstorage",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


```json
{
  "success": false,
  "error": "Authentication failed: OCI config file not found"
}
```



## S3 and S3-Compatible Storage

### `POST /api/v1/backends/s3`

Amazon S3 and S3-compatible storage. Supports AWS, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS (S3 interop), HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, Magalu, Minio, Netease, Outscale, Petabox, RackCorp, Hoody-VFS, Scaleway, SeaweedFS, Selectel, StackPath, Storj, Synology, TencentCOS, Wasabi, Qiniu, and others.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `access_key_id` | string | No | `""` | AWS Access Key ID. |
| `acl` | string | No | `""` | Canned ACL for new objects. One of `default`, `private`, `public-read`, `public-read-write`, `authenticated-read`, `bucket-owner-read`, `bucket-owner-full-control`. |
| `bucket_acl` | string | No | `""` | Canned ACL for new buckets. One of `private`, `public-read`, `public-read-write`, `authenticated-read`. |
| `chunk_size` | string | No | `"5242880"` | Upload chunk size in bytes. |
| `copy_cutoff` | string | No | `"4999610368"` | Cutoff (in bytes) for switching to multipart copy. |
| `decompress` | boolean | No | `false` | Decompress gzip-encoded objects on download. |
| `description` | string | No | `""` | Description of the remote. |
| `directory_bucket` | boolean | No | `false` | Use AWS Directory Buckets. |
| `directory_markers` | boolean | No | `false` | Persist empty folders with marker objects. |
| `disable_checksum` | boolean | No | `false` | Skip MD5 checksum calculation. |
| `disable_http2` | boolean | No | `false` | Disable HTTP/2 for the S3 backend. |
| `download_url` | string | No | `""` | Custom CDN endpoint for downloads. |
| `encoding` | string | No | `"50331650"` | Backend encoding. |
| `endpoint` | string | **Yes** | `""` | S3 API endpoint. One of the preset provider endpoints (e.g. `s3.us-east-1.amazonaws.com`, `nyc3.digitaloceanspaces.com`, `localhost:8333`) or a custom value. |
| `env_auth` | boolean | No | `false` | Get AWS credentials from the environment. |
| `force_path_style` | boolean | No | `true` | Use path-style access (vs virtual hosted style). |
| `leave_parts_on_error` | boolean | No | `false` | Leave uploaded parts on error for manual recovery. |
| `list_chunk` | integer | No | `1000` | Listing chunk size (MaxKeys). |
| `list_url_encode` | string | No | unset | URL-encode listings: `true`, `false`, or unset. |
| `list_version` | integer | No | `0` | ListObjects version: `1`, `2`, or `0` for auto. |
| `location_constraint` | string | No | `""` | Location constraint matching the region (for bucket creation). |
| `max_upload_parts` | integer | No | `10000` | Maximum number of multipart upload parts. |
| `memory_pool_flush_time` | integer | No | `60` | Internal memory pool flush time in seconds (deprecated). |
| `memory_pool_use_mmap` | boolean | No | `false` | Use mmap buffers in internal memory pool (deprecated). |
| `might_gzip` | string | No | unset | Backend may gzip objects: `true`, `false`, or unset. |
| `no_check_bucket` | boolean | No | `false` | Skip checking or creating the bucket. |
| `no_head` | boolean | No | `false` | Skip HEAD verification after upload. |
| `no_head_object` | boolean | No | `false` | Skip HEAD before GET on object reads. |
| `no_system_metadata` | boolean | No | `false` | Suppress setting and reading of system metadata. |
| `profile` | string | No | `""` | Profile to use in the shared credentials file. |
| `provider` | string | No | `""` | S3 provider preset. One of `AWS`, `Alibaba`, `ArvanCloud`, `Ceph`, `ChinaMobile`, `Cloudflare`, `DigitalOcean`, `Dreamhost`, `GCS`, `HuaweiOBS`, `IBMCOS`, `IDrive`, `IONOS`, `LyveCloud`, `Leviia`, `Liara`, `Linode`, `Magalu`, `Minio`, `Netease`, `Outscale`, `Petabox`, `RackCorp`, `Hoody-VFS`, `Scaleway`, `SeaweedFS`, `Selectel`, `StackPath`, `Storj`, `Synology`, `TencentCOS`, `Wasabi`, `Qiniu`, `Other`. |
| `region` | string | No | `""` | Region to connect to. One of `""`, `other-v2-signature`. |
| `requester_pays` | boolean | No | `false` | Enable the requester-pays option for the bucket. |
| `sdk_log_mode` | string | No | `"0"` | SDK debug log mode (e.g. `Signing`, `Request`, `All`, `Off`). |
| `secret_access_key` | string | No | `""` | AWS Secret Access Key. |
| `server_side_encryption` | string | No | `""` | SSE algorithm. One of `""`, `AES256`, `aws:kms`. |
| `session_token` | string | No | `""` | AWS session token. |
| `shared_credentials_file` | string | No | `""` | Path to the shared credentials file. |
| `sse_customer_algorithm` | string | No | `""` | SSE-C algorithm. One of `""`, `AES256`. |
| `sse_customer_key` | string | No | `""` | SSE-C encryption key. |
| `sse_customer_key_base64` | string | No | `""` | SSE-C base64-encoded key. |
| `sse_customer_key_md5` | string | No | `""` | SSE-C key MD5 checksum. |
| `sse_kms_key_id` | string | No | `""` | KMS key ARN. |
| `storage_class` | string | No | `""` | Storage class. One of `STANDARD`, `LINE`, `GLACIER`, `DEEP_ARCHIVE`. |
| `sts_endpoint` | string | No | `""` | STS endpoint (deprecated). |
| `upload_concurrency` | integer | No | `4` | Number of chunks uploaded concurrently per file. |
| `upload_cutoff` | string | No | `"209715200"` | Cutoff (in bytes) for switching to chunked upload. |
| `use_accelerate_endpoint` | boolean | No | `false` | Use the AWS S3 Transfer Acceleration endpoint. |
| `use_accept_encoding_gzip` | string | No | unset | Send `Accept-Encoding: gzip` header: `true`, `false`, or unset. |
| `use_already_exists` | string | No | unset | Report `BucketAlreadyExists` on bucket creation: `true`, `false`, or unset. |
| `use_dual_stack` | boolean | No | `false` | Use the AWS S3 dual-stack endpoint (IPv6). |
| `use_multipart_etag` | string | No | unset | Use ETag verification in multipart uploads: `true`, `false`, or unset. |
| `use_multipart_uploads` | string | No | unset | Use multipart uploads: `true`, `false`, or unset. |
| `use_presigned_request` | boolean | No | `false` | Use a presigned URL for single-part uploads. |
| `use_unsigned_payload` | string | No | unset | Use an unsigned payload for `PutObject`: `true`, `false`, or unset. |
| `v2_auth` | boolean | No | `false` | Use v2 authentication (legacy). |
| `version_at` | string | No | `"0001-01-01T00:00:00Z"` | Show file versions as they were at the specified time. |
| `version_deleted` | boolean | No | `false` | Show deleted file markers when using versions. |
| `versions` | boolean | No | `false` | Include old versions in directory listings. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/s3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "AWS",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1",
    "endpoint": "s3.us-east-1.amazonaws.com"
  }'
```


```js
await client.files.backends.connectS3({
  provider: "AWS",
  access_key_id: "AKIAIOSFODNN7EXAMPLE",
  secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  region: "us-east-1",
  endpoint: "s3.us-east-1.amazonaws.com"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_9c0d1e2f3a4b5c6d",
    "backend_type": "s3",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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



### `POST /api/v1/backends/b2`

Backblaze B2 cloud storage. Requires an Account ID/Application Key ID and Application Key.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `account` | string | **Yes** | `""` | Account ID or Application Key ID. |
| `key` | string | **Yes** | `""` | Application Key. |
| `chunk_size` | string | No | `"100663296"` | Upload chunk size in bytes (minimum 5,000,000). |
| `copy_cutoff` | string | No | `"4294967296"` | Cutoff (in bytes) for multipart copy. |
| `description` | string | No | `""` | Description of the remote. |
| `disable_checksum` | boolean | No | `false` | Skip SHA1 checksum calculation for large files. |
| `download_auth_duration` | integer | No | `604800` | Public link authorization token lifetime in seconds (max one week). |
| `download_url` | string | No | `""` | Custom endpoint for downloads (e.g. Cloudflare CDN). |
| `encoding` | string | No | `"50438146"` | Backend encoding. |
| `endpoint` | string | No | `""` | Endpoint for the service. |
| `hard_delete` | boolean | No | `false` | Permanently delete files on remote removal. |
| `lifecycle` | integer | No | `0` | Days deleted files are retained when creating a bucket. |
| `memory_pool_flush_time` | integer | No | `60` | Internal memory pool flush time in seconds (deprecated). |
| `memory_pool_use_mmap` | boolean | No | `false` | Use mmap buffers in internal memory pool (deprecated). |
| `test_mode` | string | No | `""` | X-Bz-Test-Mode flag for debugging (`fail_some_uploads`, `expire_some_account_authorization_tokens`, `force_cap_exceeded`). |
| `upload_concurrency` | integer | No | `4` | Number of chunks uploaded concurrently per file. |
| `upload_cutoff` | string | No | `"209715200"` | Cutoff (in bytes) for chunked upload (max 4.657 GiB). |
| `version_at` | string | No | `"0001-01-01T00:00:00Z"` | Show file versions as they were at the specified time. |
| `versions` | boolean | No | `false` | Include old versions in directory listings. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/b2 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "005a0b6c0b0a1b2c3d4e5f60",
    "key": "K005aAbCdEfGhIjKlMnOpQrStUvWxYz",
    "description": "Backblaze backup bucket"
  }'
```


```js
await client.files.backends.connectB2({
  account: "005a0b6c0b0a1b2c3d4e5f60",
  key: "K005aAbCdEfGhIjKlMnOpQrStUvWxYz",
  description: "Backblaze backup bucket"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_3e4f5a6b7c8d9e0f",
    "backend_type": "b2",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


```json
{
  "success": false,
  "error": "Backblaze authentication failed: invalid application key"
}
```



### `POST /api/v1/backends/qingstor`

QingCloud Object Storage. Supports zones `pek3a`, `sh1a`, and `gd2a`.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `access_key_id` | string | No | `""` | QingStor Access Key ID. |
| `secret_access_key` | string | No | `""` | QingStor Secret Access Key. |
| `endpoint` | string | No | `""` | QingStor API endpoint. |
| `zone` | string | No | `""` | Zone to connect to. One of `pek3a`, `sh1a`, `gd2a`. |
| `chunk_size` | string | No | `"4194304"` | Upload chunk size in bytes. |
| `upload_concurrency` | integer | No | `1` | Multipart upload concurrency (values &gt; 1 corrupt multipart checksums). |
| `upload_cutoff` | string | No | `"209715200"` | Cutoff (in bytes) for chunked upload (max 5 GiB). |
| `connection_retries` | integer | No | `3` | Number of connection retries. |
| `env_auth` | boolean | No | `false` | Read credentials from the environment. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"16842754"` | Backend encoding. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/qingstor \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "QINGSTOR_ACCESS_KEY",
    "secret_access_key": "QINGSTOR_SECRET_KEY",
    "zone": "pek3a"
  }'
```


```js
await client.files.backends.connectQingstor({
  access_key_id: "QINGSTOR_ACCESS_KEY",
  secret_access_key: "QINGSTOR_SECRET_KEY",
  zone: "pek3a"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_4a5b6c7d8e9f0a1b",
    "backend_type": "qingstor",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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



### `POST /api/v1/backends/cloudinary`

Cloudinary media management platform. Provides three required fields: `cloud_name`, `api_key`, and `api_secret`.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `cloud_name` | string | **Yes** | `""` | Cloudinary environment name. |
| `api_key` | string | **Yes** | `""` | Cloudinary API key. |
| `api_secret` | string | **Yes** | `""` | Cloudinary API secret. |
| `upload_preset` | string | No | `""` | Upload preset for asset manipulation on upload. |
| `upload_prefix` | string | No | `""` | API endpoint override for non-US environments. |
| `eventually_consistent_delay` | integer | No | `0` | Wait this many seconds for eventual consistency. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"52543246"` | Backend encoding. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/cloudinary \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud_name": "my-cloud",
    "api_key": "123456789012345",
    "api_secret": "abcdefghijklmnopqrstuvwxyz12"
  }'
```


```js
await client.files.backends.connectCloudinary({
  cloud_name: "my-cloud",
  api_key: "123456789012345",
  api_secret: "abcdefghijklmnopqrstuvwxyz12"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_6b7c8d9e0f1a2b3c",
    "backend_type": "cloudinary",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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



### `POST /api/v1/backends/imagekit`

ImageKit.io media management platform. Requires endpoint URL, public key, and private key from your ImageKit dashboard.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `endpoint` | string | **Yes** | `""` | ImageKit.io URL endpoint. |
| `public_key` | string | **Yes** | `""` | ImageKit.io public key. |
| `private_key` | string | **Yes** | `""` | ImageKit.io private key. |
| `only_signed` | boolean | No | `false` | Set to `true` if `Restrict unsigned image URLs` is enabled in the dashboard. |
| `upload_tags` | string | No | `""` | Tags applied to uploaded files (comma-separated). |
| `versions` | boolean | No | `false` | Include old versions in directory listings. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"117553486"` | Backend encoding. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/imagekit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://ik.imagekit.io/myid",
    "public_key": "public_xxx",
    "private_key": "private_yyy"
  }'
```


```js
await client.files.backends.connectImagekit({
  endpoint: "https://ik.imagekit.io/myid",
  public_key: "public_xxx",
  private_key: "private_yyy"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_7c8d9e0f1a2b3c4d",
    "backend_type": "imagekit",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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



## OpenStack and Enterprise

### `POST /api/v1/backends/swift`

OpenStack Swift, including Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, and OVH.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `user` | string | No | `""` | Username (OS_USERNAME). |
| `key` | string | No | `""` | API key or password (OS_PASSWORD). |
| `auth` | string | No | `""` | Auth URL. One of the preset provider URLs (e.g. `https://auth.api.rackspacecloud.com/v1.0`, `https://auth.cloud.ovh.net/v3`). |
| `auth_version` | integer | No | `0` | Auth version (`1`, `2`, or `3`) if the auth URL has none. |
| `auth_token` | string | No | `""` | Auth token from alternate authentication (OS_AUTH_TOKEN). |
| `tenant` | string | No | `""` | Tenant name (OS_TENANT_NAME or OS_PROJECT_NAME). |
| `tenant_id` | string | No | `""` | Tenant ID (OS_TENANT_ID). |
| `tenant_domain` | string | No | `""` | Tenant domain (OS_PROJECT_DOMAIN_NAME) for v3 auth. |
| `domain` | string | No | `""` | User domain (OS_USER_DOMAIN_NAME) for v3 auth. |
| `user_id` | string | No | `""` | User ID for v3 auth (OS_USER_ID). |
| `application_credential_id` | string | No | `""` | Application credential ID. |
| `application_credential_name` | string | No | `""` | Application credential name. |
| `application_credential_secret` | string | No | `""` | Application credential secret. |
| `storage_url` | string | No | `""` | Storage URL (OS_STORAGE_URL). |
| `region` | string | No | `""` | Region name (OS_REGION_NAME). |
| `endpoint_type` | string | No | `"public"` | Endpoint type. One of `public`, `internal`, `admin`. |
| `storage_policy` | string | No | `""` | Storage policy for new containers. One of `""`, `pcs`, `pca`. |
| `chunk_size` | string | No | `"5368709120"` | Files above this size (in bytes) will be chunked. |
| `no_chunk` | boolean | No | `false` | Don't chunk files during streaming upload. |
| `no_large_objects` | boolean | No | `false` | Disable static and dynamic large object support. |
| `leave_parts_on_error` | boolean | No | `false` | Leave successfully uploaded parts on error. |
| `use_segments_container` | string | No | unset | Store segment chunks in a `_segments` container (`true`/`false`/unset). |
| `fetch_until_empty_page` | boolean | No | `false` | Always fetch additional pagination pages. |
| `partial_page_fetch_threshold` | integer | No | `0` | Fetch if the current page is within this percentage of the limit. |
| `env_auth` | boolean | No | `false` | Read Swift credentials from environment variables. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"16777218"` | Backend encoding. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/swift \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "admin",
    "key": "secret-password",
    "auth": "https://auth.cloud.ovh.net/v3",
    "tenant": "1234567890123456",
    "region": "GRA1"
  }'
```


```js
await client.files.backends.connectSwift({
  user: "admin",
  key: "secret-password",
  auth: "https://auth.cloud.ovh.net/v3",
  tenant: "1234567890123456",
  region: "GRA1"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_8d9e0f1a2b3c4d5e",
    "backend_type": "swift",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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



### `POST /api/v1/backends/netstorage`

Akamai NetStorage. Requires the host, account, and secret (G2O key).

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `host` | string | **Yes** | `""` | NetStorage host in `&lt;domain&gt;/<internal folders>` format. |
| `account` | string | **Yes** | `""` | NetStorage account name. |
| `secret` | string | **Yes** | `""` | NetStorage account secret / G2O key. |
| `protocol` | string | No | `"https"` | Protocol: `http` or `https`. |
| `description` | string | No | `""` | Description of the remote. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/netstorage \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "example.akamaihd.net/1234/cpcode",
    "account": "myaccount",
    "secret": "G2O-SECRET-KEY"
  }'
```


```js
await client.files.backends.connectNetstorage({
  host: "example.akamaihd.net/1234/cpcode",
  account: "myaccount",
  secret: "G2O-SECRET-KEY"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_9e0f1a2b3c4d5e6f",
    "backend_type": "netstorage",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


```json
{
  "success": false,
  "error": "Could not authenticate with the provided NetStorage credentials"
}
```



## Decentralized and Archive Storage

### `POST /api/v1/backends/storj`

Storj Decentralized Cloud Storage. Supports authentication via access grant or via API key + passphrase.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `provider` | string | No | `"existing"` | Authentication method. One of `existing`, `new`. |
| `satellite_address` | string | No | `"us1.storj.io"` | Satellite address. One of `us1.storj.io`, `eu1.storj.io`, `ap1.storj.io` (or a custom `<nodeid>@&lt;host&gt;:&lt;port&gt;`). |
| `api_key` | string | No | `""` | API key (used with the `new` provider). |
| `passphrase` | string | No | `""` | Encryption passphrase (used with the `new` provider). |
| `access_grant` | string | No | `""` | Pre-existing access grant. |
| `description` | string | No | `""` | Description of the remote. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/storj \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "satellite_address": "us1.storj.io",
    "api_key": "jq1tj...",
    "passphrase": "my-strong-passphrase"
  }'
```


```js
await client.files.backends.connectStorj({
  satellite_address: "us1.storj.io",
  api_key: "jq1tj...",
  passphrase: "my-strong-passphrase"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_0f1a2b3c4d5e6f7a",
    "backend_type": "storj",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


```json
{
  "success": false,
  "error": "Storj authentication failed: invalid API key or passphrase"
}
```



### `POST /api/v1/backends/tardigrade`

Tardigrade (legacy Storj Decentralized Cloud Storage). Identical configuration surface to Storj; kept for compatibility with older Storj credentials.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `provider` | string | No | `"existing"` | Authentication method. One of `existing`, `new`. |
| `satellite_address` | string | No | `"us1.storj.io"` | Satellite address. One of `us1.storj.io`, `eu1.storj.io`, `ap1.storj.io` (or a custom `<nodeid>@&lt;host&gt;:&lt;port&gt;`). |
| `api_key` | string | No | `""` | API key (used with the `new` provider). |
| `passphrase` | string | No | `""` | Encryption passphrase (used with the `new` provider). |
| `access_grant` | string | No | `""` | Pre-existing access grant. |
| `description` | string | No | `""` | Description of the remote. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/tardigrade \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "access_grant": "1xCjj5c...long-access-grant-string..."
  }'
```


```js
await client.files.backends.connectTardigrade({
  access_grant: "1xCjj5c...long-access-grant-string..."
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_1a2b3c4d5e6f7a8b",
    "backend_type": "tardigrade",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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



### `POST /api/v1/backends/sia`

Sia Decentralized Cloud. Connects to a local or remote `siad` daemon over its HTTP API.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `api_url` | string | No | `"http://127.0.0.1:9980"` | Sia daemon API URL. |
| `api_password` | string | No | `""` | Sia daemon API password. |
| `user_agent` | string | No | `"Sia-Agent"` | User agent string (Sia requires `Sia-Agent` by default). |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50436354"` | Backend encoding. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/sia \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "api_url": "http://sia.daemon.host:9980",
    "api_password": "sia-api-password"
  }'
```


```js
await client.files.backends.connectSia({
  api_url: "http://sia.daemon.host:9980",
  api_password: "sia-api-password"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_2b3c4d5e6f7a8b9c",
    "backend_type": "sia",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


```json
{
  "success": false,
  "error": "Could not connect to Sia daemon at http://127.0.0.1:9980"
}
```



### `POST /api/v1/backends/internetarchive`

Internet Archive. Uses the S3-compatible IAS3 API; works with anonymous access (no credentials required for public items).

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `endpoint` | string | No | `"https://s3.us.archive.org"` | IAS3 endpoint. |
| `front_endpoint` | string | No | `"https://archive.org"` | Internet Archive frontend host. |
| `access_key_id` | string | No | `""` | IAS3 Access Key (leave blank for anonymous access). |
| `secret_access_key` | string | No | `""` | IAS3 Secret Key (leave blank for anonymous access). |
| `wait_archive` | integer | No | `0` | Timeout in seconds for server-side archive processing. |
| `disable_checksum` | boolean | No | `true` | Skip server-side MD5 checksum verification. |
| `description` | string | No | `""` | Description of the remote. |
| `encoding` | string | No | `"50446342"` | Backend encoding. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/internetarchive \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "ia-access-key",
    "secret_access_key": "ia-secret-key"
  }'
```


```js
await client.files.backends.connectInternetarchive({
  access_key_id: "ia-access-key",
  secret_access_key: "ia-secret-key"
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "bck_3c4d5e6f7a8b9c0d",
    "backend_type": "internetarchive",
    "type": "object_storage",
    "mount_paths": []
  }
}
```


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