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.

Note

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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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=="
  }'

SDK

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

Response 201

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

Response 400

{
  "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).

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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 > 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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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..."
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

{
  "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.

cURL

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"
  }'

SDK

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

Response 201

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

Response 400

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