Object Storage

Use these endpoints to register an external object storage backend with the Hoody Files service. Each endpoint persists a new remote configuration and returns a backend identifier that can later be mounted to a filesystem path inside the container. The Files service supports a broad set of providers — S3-compatible clouds, Azure, Google Cloud, Backblaze, media CDNs, archives, and decentralized networks — each with its own authentication scheme and tuning options.

All endpoints accept a JSON request body describing the backend configuration. On success the response includes the new backend’s id, its backend_type, and an empty mount_paths array; the array is populated when you subsequently mount the backend.

S3 and S3-compatible Backends

`POST /api/v1/backends/s3`

Connect an Amazon S3 or S3-compatible backend. Supported providers include 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, and others.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`endpoint`	string	Yes	Endpoint for the S3 API. Required when using an S3 clone. One of the preset provider endpoints or any custom hostname.
`access_key_id`	string	No	AWS Access Key ID. Leave blank for anonymous access or runtime credentials. Default: `""`.
`secret_access_key`	string	No	AWS Secret Access Key. Leave blank for anonymous access or runtime credentials. Default: `""`.
`region`	string	No	Region to connect to. Default: `""`. Allowed values: `""`, `other-v2-signature`.
`provider`	string	No	Choose your S3 provider. Default: `""`. Allowed values: `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`.
`acl`	string	No	Canned ACL applied when creating buckets and storing objects. Default: `""`.
`bucket_acl`	string	No	Canned ACL used when creating buckets. Default: `""`.
`chunk_size`	string	No	Chunk size for multipart uploads. Default: `"5242880"`.
`copy_cutoff`	string	No	Cutoff for switching to multipart copy (max 5 GiB). Default: `"4999610368"`.
`upload_concurrency`	integer	No	Concurrency for multipart uploads and copies. Default: `4`.
`upload_cutoff`	string	No	Cutoff for switching to chunked upload. Default: `"209715200"`.
`download_url`	string	No	Custom endpoint for downloads (e.g. a CloudFront URL). Default: `""`.
`storage_class`	string	No	Storage class for new objects (e.g. `STANDARD`, `GLACIER`). Default: `""`.
`server_side_encryption`	string	No	Server-side encryption algorithm. Allowed values: `""`, `AES256`, `aws:kms`. Default: `""`.
`session_token`	string	No	AWS session token. Default: `""`.
`profile`	string	No	Profile in the shared credentials file (used with `env_auth`). Default: `""`.
`shared_credentials_file`	string	No	Path to the shared credentials file. Default: `""`.
`env_auth`	boolean	No	Read AWS credentials from runtime (env vars or EC2/ECS meta data). Default: `false`.
`force_path_style`	boolean	No	Use path style access instead of virtual hosted style. Default: `true`.
`v2_auth`	boolean	No	Use v2 authentication instead of v4. Default: `false`.
`list_chunk`	integer	No	Size of listing chunk (MaxKeys). Default: `1000`.
`list_version`	integer	No	ListObjects version: 1, 2, or 0 for auto. Default: `0`.
`max_upload_parts`	integer	No	Maximum number of parts in a multipart upload. Default: `10000`.
`requester_pays`	boolean	No	Enable requester pays for the bucket. Default: `false`.
`no_check_bucket`	boolean	No	Skip checking/creating the bucket. Default: `false`.
`no_head`	boolean	No	Don’t HEAD uploaded objects to check integrity. Default: `false`.
`no_head_object`	boolean	No	Skip HEAD before GET when getting objects. Default: `false`.
`disable_checksum`	boolean	No	Skip storing MD5 checksum with object metadata. Default: `false`.
`disable_http2`	boolean	No	Disable HTTP/2 for the S3 backend. Default: `false`.
`decompress`	boolean	No	Decompress gzip-encoded objects on download. Default: `false`.
`directory_markers`	boolean	No	Upload empty marker objects for directories. Default: `false`.
`directory_bucket`	boolean	No	Configure for AWS Directory Buckets. Default: `false`.
`leave_parts_on_error`	boolean	No	Leave uploaded parts on S3 after a failure (for manual recovery). Default: `false`.
`use_accelerate_endpoint`	boolean	No	Use AWS S3 accelerated endpoint. Default: `false`.
`use_dual_stack`	boolean	No	Use AWS S3 dual-stack endpoint (IPv6). Default: `false`.
`use_presigned_request`	boolean	No	Use a presigned request for single part uploads. Default: `false`.
`sts_endpoint`	string	No	Endpoint for STS (deprecated). Default: `""`.
`sdk_log_mode`	string	No	SDK debug log levels. Default: `"0"`.
`location_constraint`	string	No	Location constraint matching the region. Default: `""`.
`encoding`	string	No	Backend encoding. Default: `"50331650"`.
`description`	string	No	Description of the remote. Default: `""`.
`version_at`	string	No	Show file versions as of a specific time. Default: `"0001-01-01T00:00:00Z"`.
`versions`	boolean	No	Include old versions in directory listings. Default: `false`.
`version_deleted`	boolean	No	Show deleted file markers when using versions. Default: `false`.
`memory_pool_flush_time`	integer	No	Legacy: memory buffer flush interval (seconds). Default: `60`.
`memory_pool_use_mmap`	boolean	No	Legacy: use mmap in the memory pool. Default: `false`.
`no_system_metadata`	boolean	No	Suppress setting and reading of system metadata. Default: `false`.
`list_url_encode`	string	No	URL-encode listings (unset/true/false). Default: `{"Valid":false,"Value":false}`.
`might_gzip`	string	No	Backend may gzip objects (unset/true/false). Default: `{"Valid":false,"Value":false}`.
`use_accept_encoding_gzip`	string	No	Send `Accept-Encoding: gzip` header (unset/true/false). Default: `{"Valid":false,"Value":false}`.
`use_already_exists`	string	No	Report `BucketAlreadyExists` errors on bucket creation (unset/true/false). Default: `{"Valid":false,"Value":false}`.
`use_multipart_etag`	string	No	Use ETag for multipart upload verification (unset/true/false). Default: `{"Valid":false,"Value":false}`.
`use_multipart_uploads`	string	No	Use multipart uploads (unset/true/false). Default: `{"Valid":false,"Value":false}`.
`use_unsigned_payload`	string	No	Use unsigned payload in PutObject (unset/true/false). Default: `{"Valid":false,"Value":false}`.
`sse_customer_algorithm`	string	No	SSE-C encryption algorithm. Allowed values: `""`, `AES256`. Default: `""`.
`sse_customer_key`	string	No	SSE-C encryption key. Default: `""`.
`sse_customer_key_base64`	string	No	SSE-C encryption key (base64). Default: `""`.
`sse_customer_key_md5`	string	No	SSE-C encryption key MD5 checksum. Default: `""`.
`sse_kms_key_id`	string	No	KMS Key ARN. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7c9",
    "type": "remote",
    "backend_type": "s3",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "Failed to connect to endpoint: connection refused"
}

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/s3 \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "s3.us-east-1.amazonaws.com",
    "provider": "AWS",
    "region": "us-east-1",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

`POST /api/v1/backends/azureblob`

Connect a Microsoft Azure Blob Storage backend. Supports shared keys, SAS URLs, service principals, certificates, MSI, the az CLI, and an emulator.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`account`	string	No	Azure Storage Account Name. Leave blank for SAS URL or Emulator. Default: `""`.
`key`	string	No	Storage Account Shared Key. Leave blank for SAS URL or Emulator. Default: `""`.
`sas_url`	string	No	SAS URL for container-level access. Default: `""`.
`tenant`	string	No	Service principal tenant/directory ID. Default: `""`.
`client_id`	string	No	Client ID (service principal or user). Default: `""`.
`client_secret`	string	No	Service principal client secret. Default: `""`.
`client_certificate_path`	string	No	Path to PEM or PKCS12 certificate. Default: `""`.
`client_certificate_password`	string	No	Certificate password. Default: `""`.
`client_send_certificate_chain`	boolean	No	Send the certificate chain (x5c) when using certificate auth. Default: `false`.
`service_principal_file`	string	No	Path to a service principal credentials file. Default: `""`.
`username`	string	No	Username (usually an email) for user/password auth. Default: `""`.
`password`	string	No	User password. Default: `""`.
`use_msi`	boolean	No	Use a managed service identity for auth. Default: `false`.
`msi_object_id`	string	No	Object ID of the user-assigned MSI. Default: `""`.
`msi_client_id`	string	No	Client ID of the user-assigned MSI. Default: `""`.
`msi_mi_res_id`	string	No	Azure resource ID of the user-assigned MSI. Default: `""`.
`use_az`	boolean	No	Use Azure CLI (`az`) for authentication. Default: `false`.
`env_auth`	boolean	No	Read credentials from runtime (env vars, CLI, MSI). Default: `false`.
`use_emulator`	boolean	No	Use the local Azure storage emulator. Default: `false`.
`endpoint`	string	No	Endpoint for the service. Leave blank normally. Default: `""`.
`access_tier`	string	No	Access tier of blobs (hot, cool, cold, archive). Default: `""`.
`archive_tier_delete`	boolean	No	Delete archive tier blobs before overwriting. Default: `false`.
`public_access`	string	No	Container public access level. Allowed values: `""`, `blob`, `container`. Default: `""`.
`delete_snapshots`	string	No	How to handle snapshots on blob deletion. Allowed values: `""`, `include`, `only`. Default: `""`.
`directory_markers`	boolean	No	Upload empty marker objects for directories. Default: `false`.
`disable_checksum`	boolean	No	Skip storing MD5 checksum with object metadata. Default: `false`.
`disable_instance_discovery`	boolean	No	Skip Microsoft Entra instance metadata request. Default: `false`.
`no_check_container`	boolean	No	Skip checking/creating the container. Default: `false`.
`no_head_object`	boolean	No	Skip HEAD before GET on objects. Default: `false`.
`chunk_size`	string	No	Upload chunk size. Default: `"4194304"`.
`upload_concurrency`	integer	No	Concurrency for multipart uploads. Default: `16`.
`upload_cutoff`	string	No	Cutoff for chunked upload (deprecated). Default: `""`.
`list_chunk`	integer	No	Blob list chunk size (max 5000). Default: `5000`.
`encoding`	string	No	Backend encoding. Default: `"21078018"`.
`memory_pool_flush_time`	integer	No	Legacy: memory buffer flush interval (seconds). Default: `60`.
`memory_pool_use_mmap`	boolean	No	Legacy: use mmap in the memory pool. Default: `false`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7ca",
    "type": "remote",
    "backend_type": "azureblob",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "invalid storage account credentials"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/azureblob \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "mystorageaccount",
    "key": "example-azure-shared-key==",
    "access_tier": "hot",
    "public_access": "blob"
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.files.backends.connectAzureblob({
  account: "mystorageaccount",
  key: "example-azure-shared-key==",
  access_tier: "hot",
  public_access: "blob"
});

`POST /api/v1/backends/azurefiles`

Connect a Microsoft Azure Files (SMB share) backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`account`	string	No	Azure Storage Account Name. Default: `""`.
`key`	string	No	Storage Account Shared Key. Default: `""`.
`sas_url`	string	No	SAS URL for the share. Default: `""`.
`connection_string`	string	No	Azure Files connection string. Default: `""`.
`share_name`	string	No	Azure Files share name (required to access a share). Default: `""`.
`tenant`	string	No	Service principal tenant/directory ID. Default: `""`.
`client_id`	string	No	Client ID. Default: `""`.
`client_secret`	string	No	Service principal client secret. Default: `""`.
`client_certificate_path`	string	No	Path to PEM or PKCS12 certificate. Default: `""`.
`client_certificate_password`	string	No	Certificate password. Default: `""`.
`client_send_certificate_chain`	boolean	No	Send the certificate chain when using certificate auth. Default: `false`.
`service_principal_file`	string	No	Path to a service principal credentials file. Default: `""`.
`username`	string	No	Username (usually an email). Default: `""`.
`password`	string	No	User password. Default: `""`.
`use_msi`	boolean	No	Use a managed service identity for auth. Default: `false`.
`msi_object_id`	string	No	Object ID of the user-assigned MSI. Default: `""`.
`msi_client_id`	string	No	Client ID of the user-assigned MSI. Default: `""`.
`msi_mi_res_id`	string	No	Azure resource ID of the user-assigned MSI. Default: `""`.
`env_auth`	boolean	No	Read credentials from runtime. Default: `false`.
`endpoint`	string	No	Endpoint for the service. Default: `""`.
`chunk_size`	string	No	Upload chunk size. Default: `"4194304"`.
`upload_concurrency`	integer	No	Concurrency for multipart uploads. Default: `16`.
`max_stream_size`	string	No	Maximum streamed file size (default pre-allocated). Default: `"10737418240"`.
`encoding`	string	No	Backend encoding. Default: `"54634382"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7cb",
    "type": "remote",
    "backend_type": "azurefiles",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "share not found: myshare"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/azurefiles \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "mystorageaccount",
    "share_name": "myshare",
    "key": "example-azure-shared-key=="
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

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

Connect a Google Cloud Storage backend. Supports service accounts, OAuth client credentials, anonymous public-bucket access, and runtime credentials.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`access_token`	string	No	Short-lived access token. Default: `""`.
`service_account_file`	string	No	Path to Service Account JSON file. Default: `""`.
`service_account_credentials`	string	No	Service Account credentials JSON blob. Default: `""`.
`anonymous`	boolean	No	Access public buckets/objects without credentials. Default: `false`.
`auth_url`	string	No	Auth server URL. Default: `""`.
`token`	string	No	OAuth access token as JSON blob. Default: `""`.
`token_url`	string	No	Token server URL. Default: `""`.
`client_credentials`	boolean	No	Use OAuth2 client credentials flow (RFC 6749). Default: `false`.
`client_id`	string	No	OAuth client ID. Default: `""`.
`client_secret`	string	No	OAuth client secret. Default: `""`.
`project_number`	string	No	GCP project number (for list/create/delete buckets). Default: `""`.
`user_project`	string	No	User project (for requester pays buckets). Default: `""`.
`env_auth`	boolean	No	Get GCP IAM credentials from runtime (env or instance metadata). Allowed values: `"false"`, `"true"`. Default: `false`.
`location`	string	No	Location for newly created buckets. Default: `""`. See spec for allowed enum values.
`storage_class`	string	No	Storage class for new objects. Allowed values: `""`, `MULTI_REGIONAL`, `REGIONAL`, `NEARLINE`, `COLDLINE`, `ARCHIVE`, `DURABLE_REDUCED_AVAILABILITY`. Default: `""`.
`bucket_acl`	string	No	ACL for new buckets. Allowed values: `authenticatedRead`, `private`, `projectPrivate`, `publicRead`, `publicReadWrite`. Default: `""`.
`object_acl`	string	No	ACL for new objects. Allowed values: `authenticatedRead`, `bucketOwnerFullControl`, `bucketOwnerRead`, `private`, `projectPrivate`, `publicRead`. Default: `""`.
`bucket_policy_only`	boolean	No	Use bucket-level IAM policies. Default: `false`.
`no_check_bucket`	boolean	No	Skip checking/creating the bucket. Default: `false`.
`decompress`	boolean	No	Decompress gzip-encoded objects on download. Default: `false`.
`directory_markers`	boolean	No	Upload empty marker objects for directories. Default: `false`.
`endpoint`	string	No	Endpoint for the service. Default: `""`.
`encoding`	string	No	Backend encoding. Default: `"50348034"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

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

{
  "success": false,
  "error": "service account credentials are not valid JSON"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/google-cloud-storage \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_file": "/etc/gcp/sa-key.json",
    "project_number": "123456789012",
    "location": "us-central1",
    "storage_class": "STANDARD"
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

`POST /api/v1/backends/oracleobjectstorage`

Connect an Oracle Cloud Infrastructure Object Storage backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`provider`	string	Yes	Authentication provider. Allowed values: `env_auth`, `user_principal_auth`, `instance_principal_auth`, `workload_identity_auth`, `resource_principal_auth`, `no_auth`. Default: `"env_auth"`.
`namespace`	string	Yes	Object storage namespace. Default: `""`.
`region`	string	Yes	Object storage region. Default: `""`.
`config_file`	string	No	Path to OCI config file. Default: `"~/.oci/config"`.
`config_profile`	string	No	Profile name inside the OCI config file. Default: `"Default"`.
`compartment`	string	No	Compartment OCID (for listing buckets). Default: `""`.
`endpoint`	string	No	Endpoint for the Object Storage API. Default: `""`.
`storage_tier`	string	No	Storage class for new objects. Allowed values: `Standard`, `InfrequentAccess`, `Archive`. Default: `"Standard"`.
`chunk_size`	string	No	Chunk size for multipart uploads. Default: `"5242880"`.
`upload_concurrency`	integer	No	Concurrency for multipart uploads. Default: `10`.
`upload_cutoff`	string	No	Cutoff for chunked upload. Default: `"209715200"`.
`copy_cutoff`	string	No	Cutoff for multipart copy (max 5 GiB). Default: `"4999610368"`.
`copy_timeout`	integer	No	Timeout for copy operations (seconds). Default: `60`.
`max_upload_parts`	integer	No	Maximum multipart upload parts. Default: `10000`.
`no_check_bucket`	boolean	No	Skip checking/creating the bucket. Default: `false`.
`disable_checksum`	boolean	No	Skip MD5 checksum storage. Default: `false`.
`attempt_resume_upload`	boolean	No	Attempt to resume a previously started multipart upload. Default: `false`.
`leave_parts_on_error`	boolean	No	Leave uploaded parts on failure (for manual recovery). Default: `false`.
`sse_customer_algorithm`	string	No	SSE-C encryption algorithm. Allowed values: `""`, `AES256`. Default: `""`.
`sse_customer_key`	string	No	Base64 SSE-C encryption key. Default: `""`.
`sse_customer_key_file`	string	No	File with the SSE-C encryption key. Default: `""`.
`sse_customer_key_sha256`	string	No	Base64 SHA256 of the SSE-C key. Default: `""`.
`sse_kms_key_id`	string	No	OCI Vault master encryption key OCID. Default: `""`.
`encoding`	string	No	Backend encoding. Default: `"50331650"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7cd",
    "type": "remote",
    "backend_type": "oracleobjectstorage",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "unable to read OCI config file: ~/.oci/config"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/oracleobjectstorage \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "user_principal_auth",
    "namespace": "axamplehi3w5p7nm",
    "region": "us-ashburn-1",
    "compartment": "ocid1.compartment.oc1..example"
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

`POST /api/v1/backends/qingstor`

Connect a QingCloud Object Storage (QingStor) backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`access_key_id`	string	No	QingStor Access Key ID. Default: `""`.
`secret_access_key`	string	No	QingStor Secret Access Key. Default: `""`.
`env_auth`	boolean	No	Get QingStor credentials from runtime. Allowed values: `"false"`, `"true"`. Default: `false`.
`endpoint`	string	No	QingStor API endpoint. Default: `""`.
`zone`	string	No	Zone to connect to. Allowed values: `pek3a`, `sh1a`, `gd2a`. Default: `""`.
`chunk_size`	string	No	Upload chunk size. Default: `"4194304"`.
`upload_concurrency`	integer	No	Concurrency for multipart uploads. Default: `1`.
`upload_cutoff`	string	No	Cutoff for chunked upload. Default: `"209715200"`.
`connection_retries`	integer	No	Number of connection retries. Default: `3`.
`encoding`	string	No	Backend encoding. Default: `"16842754"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7ce",
    "type": "remote",
    "backend_type": "qingstor",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "invalid QingStor credentials"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/qingstor \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "qingstor-access-key",
    "secret_access_key": "qingstor-secret-key",
    "zone": "pek3a"
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.files.backends.connectQingstor({
  access_key_id: "qingstor-access-key",
  secret_access_key: "qingstor-secret-key",
  zone: "pek3a"
});

`POST /api/v1/backends/b2`

Connect a Backblaze B2 backend. The account and key fields are required for authenticated access.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`account`	string	Yes	Account ID or Application Key ID. Default: `""`.
`key`	string	Yes	Application Key. Default: `""`.
`endpoint`	string	No	Endpoint for the service. Default: `""`.
`download_url`	string	No	Custom CDN endpoint for downloads (e.g. Cloudflare). Default: `""`.
`hard_delete`	boolean	No	Permanently delete files on remote removal. Default: `false`.
`lifecycle`	integer	No	Days to keep deleted/overwritten files before permanent deletion. Default: `0`.
`versions`	boolean	No	Include old versions in directory listings. Default: `false`.
`version_at`	string	No	Show file versions as of a specific time. Default: `"0001-01-01T00:00:00Z"`.
`download_auth_duration`	integer	No	Validity of public link authorization tokens (seconds, max 1 week). Default: `604800`.
`chunk_size`	string	No	Upload chunk size (min 5,000,000 bytes). Default: `"100663296"`.
`upload_concurrency`	integer	No	Concurrency for multipart uploads. Default: `4`.
`upload_cutoff`	string	No	Cutoff for chunked upload (max 4.657 GiB). Default: `"209715200"`.
`copy_cutoff`	string	No	Cutoff for multipart copy (max 4.6 GiB). Default: `"4294967296"`.
`disable_checksum`	boolean	No	Disable SHA1 checksums for large files. Default: `false`.
`test_mode`	string	No	X-Bz-Test-Mode header for debugging B2. Default: `""`.
`encoding`	string	No	Backend encoding. Default: `"50438146"`.
`memory_pool_flush_time`	integer	No	Legacy: memory buffer flush interval (seconds). Default: `60`.
`memory_pool_use_mmap`	boolean	No	Legacy: use mmap in the memory pool. Default: `false`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7cf",
    "type": "remote",
    "backend_type": "b2",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "Backblaze authentication failed"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/b2 \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "b2-account-id",
    "key": "b2-application-key",
    "hard_delete": true,
    "lifecycle": 30
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.files.backends.connectB2({
  account: "b2-account-id",
  key: "b2-application-key",
  hard_delete: true,
  lifecycle: 30
});

Media and Archive Services

`POST /api/v1/backends/cloudinary`

Connect a Cloudinary media backend. The cloud_name, api_key, and api_secret fields are required.

This endpoint takes no parameters.

Request Body

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

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d0",
    "type": "remote",
    "backend_type": "cloudinary",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "invalid Cloudinary credentials"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/cloudinary \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud_name": "demo-cloud",
    "api_key": "123456789012345",
    "api_secret": "abcdefghijklmnopqrstuvwxyz12"
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

`POST /api/v1/backends/imagekit`

Connect an ImageKit.io media backend. The endpoint, public_key, and private_key fields are required.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`endpoint`	string	Yes	ImageKit.io URL endpoint (from the developer dashboard). Default: `""`.
`public_key`	string	Yes	ImageKit.io public key. Default: `""`.
`private_key`	string	Yes	ImageKit.io private key. Default: `""`.
`only_signed`	boolean	No	Enable if `Restrict unsigned image URLs` is set in ImageKit settings. Default: `false`.
`upload_tags`	string	No	Tags to add to uploaded files (e.g. `tag1,tag2`). Default: `""`.
`versions`	boolean	No	Include old versions in directory listings. Default: `false`.
`encoding`	string	No	Backend encoding. Default: `"117553486"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d1",
    "type": "remote",
    "backend_type": "imagekit",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "could not reach endpoint https://ik.imagekit.io/demo"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/imagekit \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://ik.imagekit.io/demo",
    "public_key": "public_abc123",
    "private_key": "private_xyz789"
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.files.backends.connectImagekit({
  endpoint: "https://ik.imagekit.io/demo",
  public_key: "public_abc123",
  private_key: "private_xyz789"
});

`POST /api/v1/backends/internetarchive`

Connect an Internet Archive backend. Set the IAS3 access and secret keys for authenticated access; leave them blank for anonymous access.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`access_key_id`	string	No	IAS3 Access Key. Leave blank for anonymous access. Default: `""`.
`secret_access_key`	string	No	IAS3 Secret Key. Leave blank for anonymous access. Default: `""`.
`endpoint`	string	No	IAS3 endpoint. Default: `"https://s3.us.archive.org"`.
`front_endpoint`	string	No	Host of the Internet Archive frontend. Default: `"https://archive.org"`.
`disable_checksum`	boolean	No	Skip MD5 checksum verification by the server. Default: `true`.
`wait_archive`	integer	No	Seconds to wait for archive/book_op processing tasks (0 disables). Default: `0`.
`encoding`	string	No	Backend encoding. Default: `"50446342"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d2",
    "type": "remote",
    "backend_type": "internetarchive",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "invalid IAS3 access key"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/internetarchive \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "ia-access-key",
    "secret_access_key": "ia-secret-key"
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

Other Cloud Storage

`POST /api/v1/backends/netstorage`

Connect an Akamai NetStorage backend. The host, account, and secret fields are required.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`host`	string	Yes	Domain and internal path of the NetStorage host (`<domain>/<folders>`). Default: `""`.
`account`	string	Yes	NetStorage account name. Default: `""`.
`secret`	string	Yes	NetStorage account secret / G2O key. Default: `""`.
`protocol`	string	No	Connection protocol. Allowed values: `http`, `https`. Default: `"https"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d3",
    "type": "remote",
    "backend_type": "netstorage",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "unable to authenticate with NetStorage"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/netstorage \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "my-ns.host.example.com/internal/path",
    "account": "myaccount",
    "secret": "g2o-secret-value"
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.files.backends.connectNetstorage({
  host: "my-ns.host.example.com/internal/path",
  account: "myaccount",
  secret: "g2o-secret-value"
});

`POST /api/v1/backends/swift`

Connect an OpenStack Swift backend. Used with Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, and OVH.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`auth`	string	No	Authentication URL (OS_AUTH_URL). Default: `""`. Allowed presets: Rackspace, Memset, OVH endpoints.
`auth_version`	integer	No	Auth version (1, 2, or 3) when the auth URL has no version. Default: `0`.
`user`	string	No	Username (OS_USERNAME). Default: `""`.
`user_id`	string	No	User ID for v3 auth (OS_USER_ID). Default: `""`.
`key`	string	No	API key or password (OS_PASSWORD). Default: `""`.
`auth_token`	string	No	Auth token from alternate authentication (OS_AUTH_TOKEN). Default: `""`.
`tenant`	string	No	Tenant name (OS_TENANT_NAME / OS_PROJECT_NAME). Default: `""`.
`tenant_id`	string	No	Tenant ID (OS_TENANT_ID). Default: `""`.
`tenant_domain`	string	No	Tenant domain for v3 auth (OS_PROJECT_DOMAIN_NAME). Default: `""`.
`domain`	string	No	User domain for v3 auth (OS_USER_DOMAIN_NAME). Default: `""`.
`application_credential_id`	string	No	Application credential ID. Default: `""`.
`application_credential_name`	string	No	Application credential name. Default: `""`.
`application_credential_secret`	string	No	Application credential secret. Default: `""`.
`region`	string	No	Region name (OS_REGION_NAME). Default: `""`.
`storage_url`	string	No	Storage URL (OS_STORAGE_URL). Default: `""`.
`endpoint_type`	string	No	Endpoint type from the service catalogue. Allowed values: `public`, `internal`, `admin`. Default: `"public"`.
`storage_policy`	string	No	Storage policy for new containers. Allowed values: `""`, `pcs`, `pca`. Default: `""`.
`env_auth`	boolean	No	Get Swift credentials from environment variables. Allowed values: `"false"`, `"true"`. Default: `false`.
`chunk_size`	string	No	Files above this size will be chunked. Default: `"5368709120"`.
`no_chunk`	boolean	No	Don’t chunk files during streaming upload. Default: `false`.
`no_large_objects`	boolean	No	Disable static and dynamic large objects. Default: `false`.
`leave_parts_on_error`	boolean	No	Avoid calling abort upload on failure. Default: `false`.
`fetch_until_empty_page`	boolean	No	Always paginate unless an empty page is received. Default: `false`.
`partial_page_fetch_threshold`	integer	No	Fetch if the current page is within this percent of the limit. Default: `0`.
`use_segments_container`	string	No	Where to store large-object segments. Default: `{"Valid":false,"Value":false}`.
`encoding`	string	No	Backend encoding. Default: `"16777218"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d4",
    "type": "remote",
    "backend_type": "swift",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "OpenStack authentication failed for tenant mytenant"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/swift \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "auth": "https://auth.cloud.ovh.net/v3",
    "auth_version": 3,
    "user": "swift-user",
    "key": "swift-password",
    "tenant": "mytenant",
    "region": "GRA1"
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

Decentralized Storage

`POST /api/v1/backends/sia`

Connect a Sia decentralized cloud backend by pointing to a running siad daemon.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`api_url`	string	No	Sia daemon API URL (e.g. `http://sia.daemon.host:9980`). Default: `"http://127.0.0.1:9980"`.
`api_password`	string	No	Sia daemon API password (from the apipassword file). Default: `""`.
`user_agent`	string	No	User agent sent to the daemon. Default: `"Sia-Agent"`.
`encoding`	string	No	Backend encoding. Default: `"50436354"`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d5",
    "type": "remote",
    "backend_type": "sia",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "could not reach Sia daemon at http://127.0.0.1:9980"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/sia \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "api_url": "http://sia.daemon.host:9980",
    "api_password": "sia-api-password"
  }'

import { HoodyClient } from 'hoody-sdk';

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

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

`POST /api/v1/backends/storj`

Connect a Storj decentralized cloud storage backend. The provider field selects whether to use an existing access grant or to create a new one with an API key and passphrase.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`provider`	string	No	Authentication method. Allowed values: `existing`, `new`. Default: `"existing"`.
`satellite_address`	string	No	Satellite address. Allowed values: `us1.storj.io`, `eu1.storj.io`, `ap1.storj.io`. Default: `"us1.storj.io"`.
`access_grant`	string	No	Access grant (used with `provider=existing`). Default: `""`.
`api_key`	string	No	API key (used with `provider=new`). Default: `""`.
`passphrase`	string	No	Encryption passphrase. Default: `""`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d6",
    "type": "remote",
    "backend_type": "storj",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "invalid Storj access grant"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/storj \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "existing",
    "satellite_address": "us1.storj.io",
    "access_grant": "1abc2def3ghi..."
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.files.backends.connectStorj({
  provider: "existing",
  satellite_address: "us1.storj.io",
  access_grant: "1abc2def3ghi..."
});

`POST /api/v1/backends/tardigrade`

Connect a Tardigrade backend. Tardigrade was the original name for the Storj network; the configuration fields are identical to the Storj backend.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Description
`provider`	string	No	Authentication method. Allowed values: `existing`, `new`. Default: `"existing"`.
`satellite_address`	string	No	Satellite address. Allowed values: `us1.storj.io`, `eu1.storj.io`, `ap1.storj.io`. Default: `"us1.storj.io"`.
`access_grant`	string	No	Access grant (used with `provider=existing`). Default: `""`.
`api_key`	string	No	API key (used with `provider=new`). Default: `""`.
`passphrase`	string	No	Encryption passphrase. Default: `""`.
`description`	string	No	Description of the remote. Default: `""`.

Response

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "68d3f1a24c5e9b0012a4f7d7",
    "type": "remote",
    "backend_type": "tardigrade",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "invalid Tardigrade access grant"
}

Example

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/tardigrade \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "existing",
    "satellite_address": "eu1.storj.io",
    "access_grant": "1abc2def3ghi..."
  }'

import { HoodyClient } from 'hoody-sdk';

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

await client.files.backends.connectTardigrade({
  provider: "existing",
  satellite_address: "eu1.storj.io",
  access_grant: "1abc2def3ghi..."
});