Object Storage

Connect cloud object storage backends to a container’s filesystem. Each endpoint registers a new backend with the files service. Once connected, the backend can be mounted and accessed like any other storage provider.

All endpoints accept a JSON body describing the backend, return a backend identifier on success, and target the container-scoped hostname below.

Host

https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com

Note

Replace {projectId} and {containerId} with your project’s and container’s identifiers, and {server} with the node label such as node-example-1. All requests require a bearer token in the Authorization header.

Microsoft Azure

POST /api/v1/backends/azureblob

Connect a Microsoft Azure Blob Storage backend.

This endpoint takes no parameters.

Request body

All fields are optional. Provide credentials through account/key or sas_url. env_auth, use_msi, and use_az accept only false: runtime credentials are not available.

Name	Type	Default	Required	Description
access_tier	string	""	No	Access tier for uploaded blobs (hot, cool, cold, or archive).
account	string	""	No	Azure Storage Account Name.
archive_tier_delete	boolean	false	No	Delete archive tier blobs before overwriting them.
chunk_size	string	"4194304"	No	Upload chunk size in bytes.
client_certificate_password	string (password)	""	No	Password for the certificate file.
client_id	string	""	No	The ID of the client in use.
client_secret	string	""	No	One of the service principal’s client secrets.
client_send_certificate_chain	boolean	false	No	Send the certificate chain when using certificate auth.
copy_concurrency	integer	512	No	Concurrency for multipart copy.
copy_cutoff	string	"8388608"	No	Cutoff for switching to multipart copy.
copy_total_concurrency	integer	0	No	Global concurrency limit for multipart copy chunks.
decompress	boolean	false	No	If set, decompress gzip-encoded objects on download.
delete_snapshots	string (enum: "", include, only)	""	No	How to handle snapshots on blob deletion.
description	string	""	No	Description of the remote.
directory_markers	boolean	false	No	Upload empty objects ending with / for new directories.
disable_checksum	boolean	false	No	Don’t store MD5 checksum with object metadata.
disable_instance_discovery	boolean	false	No	Skip requesting Microsoft Entra instance metadata.
encoding	string	"21078018"	No	The encoding for the backend.
endpoint	string	""	No	Endpoint for the service.
env_auth	boolean (enum: false)	false	No	Read credentials from runtime (environment variables, CLI, or MSI).
key	string	""	No	Storage Account Shared Key.
list_chunk	integer	5000	No	Size of blob list per request.
list_parallelism	integer	0	No	Number of parallel shards to list a directory with.
memory_pool_flush_time	integer	60	No	Memory buffer pool flush interval, in seconds (no longer used).
memory_pool_use_mmap	boolean	false	No	Use mmap buffers in internal memory pool (no longer used).
msi_client_id	string	""	No	Client ID of the user-assigned MSI to use.
msi_mi_res_id	string	""	No	Azure resource ID of the user-assigned MSI to use.
msi_object_id	string	""	No	Object ID of the user-assigned MSI to use.
no_check_container	boolean	false	No	Don’t check that the container exists or create it.
no_head_object	boolean	false	No	Don’t do HEAD before GET when getting objects.
password	string (password)	""	No	User’s password (user with username/password auth).
public_access	string (enum: "", blob, container)	""	No	Public access level of the container.
sas_url	string	""	No	SAS URL for container-level access only.
tenant	string	""	No	ID of the service principal’s tenant.
upload_concurrency	integer	16	No	Concurrency for multipart uploads.
upload_cutoff	string	""	No	Cutoff for switching to chunked upload (deprecated).
use_arrow_list	boolean	false	No	Use the experimental Apache Arrow listing format.
use_az	boolean (enum: false)	false	No	Use Azure CLI tool az for authentication.
use_copy_blob	boolean	true	No	Whether to use the Copy Blob API when copying to the same storage account.
use_emulator	boolean (enum: false)	false	No	Use the local Azure storage emulator.
use_msi	boolean (enum: false)	false	No	Use a managed service identity to authenticate.
username	string	""	No	Username (usually an email address).

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/azureblob \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "mystorageaccount",
    "key": "<account-shared-key>",
    "access_tier": "hot",
    "description": "Azure Blob production backups"
  }'

TypeScript SDK

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.createAzureblob({
  account: 'mystorageaccount',
  key: '<account-shared-key>',
  access_tier: 'hot',
  description: 'Azure Blob production backups'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "azureblob",
    "vfs_backend_type": "azureblob",
    "config": {
      "account": "mystorageaccount",
      "key": "***",
      "access_tier": "hot",
      "description": "Azure Blob production backups"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/azurefiles

Connect a Microsoft Azure Files backend.

This endpoint takes no parameters.

Request body

All fields are optional. Provide credentials through account/key or sas_url. env_auth, use_msi, and use_az accept only false: runtime credentials are not available. share_name is strongly recommended.

Name	Type	Default	Required	Description
account	string	""	No	Azure Storage Account Name.
chunk_size	string	"4194304"	No	Upload chunk size in bytes.
client_certificate_password	string (password)	""	No	Password for the certificate file.
client_id	string	""	No	The ID of the client in use.
client_secret	string	""	No	One of the service principal’s client secrets.
client_send_certificate_chain	boolean	false	No	Send the certificate chain when using certificate auth.
description	string	""	No	Description of the remote.
disable_instance_discovery	boolean	false	No	Skip requesting Microsoft Entra instance metadata.
encoding	string	"54634382"	No	The encoding for the backend.
endpoint	string	""	No	Endpoint for the service.
env_auth	boolean (enum: false)	false	No	Read credentials from runtime.
key	string	""	No	Storage Account Shared Key.
max_stream_size	string	"10737418240"	No	Max size for streamed files.
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 (password)	""	No	User’s password.
sas_url	string	""	No	SAS URL.
share_name	string	""	No	Azure Files Share Name.
tenant	string	""	No	ID of the service principal’s tenant.
upload_concurrency	integer	16	No	Concurrency for multipart uploads.
use_az	boolean (enum: false)	false	No	Use Azure CLI tool az for authentication.
use_emulator	boolean (enum: false)	false	No	Use the local Azure storage emulator.
use_msi	boolean (enum: false)	false	No	Use a managed service identity to authenticate.
username	string	""	No	Username (usually an email address).

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/azurefiles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "mystorageaccount",
    "share_name": "production",
    "key": "<account-shared-key>",
    "description": "Azure Files production share"
  }'

TypeScript SDK

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.createAzurefiles({
  account: 'mystorageaccount',
  share_name: 'production',
  key: '<account-shared-key>',
  description: 'Azure Files production share'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "azurefiles",
    "vfs_backend_type": "azurefiles",
    "config": {
      "account": "mystorageaccount",
      "share_name": "production",
      "key": "***",
      "description": "Azure Files production share"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

Cloud object storage

POST /api/v1/backends/b2

Connect a Backblaze B2 backend.

This endpoint takes no parameters.

Request body

Name	Type	Default	Required	Description
account	string	""	Yes	Account ID or Application Key ID.
key	string	""	Yes	Application Key.
chunk_size	string	"100663296"	No	Upload chunk size in bytes.
copy_cutoff	string	"4294967296"	No	Cutoff for switching to multipart copy.
description	string	""	No	Description of the remote.
disable_checksum	boolean	false	No	Disable checksums for large files.
download_auth_duration	integer	604800	No	Public link authorization token lifetime, in seconds.
download_url	string	""	No	Custom endpoint for downloads (e.g. a Cloudflare CDN URL).
encoding	string	"50438146"	No	The encoding for the backend.
endpoint	string	""	No	Endpoint for the service.
hard_delete	boolean	false	No	Permanently delete files on remote removal.
lifecycle	integer	0	No	Days deleted files are kept when creating a bucket.
memory_pool_flush_time	integer	60	No	Memory buffer pool flush interval, in seconds (no longer used).
memory_pool_use_mmap	boolean	false	No	Use mmap buffers in internal memory pool (no longer used).
sse_customer_algorithm	string (enum: "", AES256)	""	No	If using SSE-C, the server-side encryption algorithm used when storing this object in B2.
sse_customer_key	string	""	No	Secret encryption key (UTF-8) for SSE-C.
sse_customer_key_base64	string	""	No	Secret encryption key (Base64) for SSE-C.
sse_customer_key_md5	string	""	No	Optional MD5 checksum of the SSE-C encryption key.
test_mode	string	""	No	Debug flag for the X-Bz-Test-Mode header.
upload_concurrency	integer	4	No	Concurrency for multipart uploads.
upload_cutoff	string	"209715200"	No	Cutoff for switching to chunked upload.
version_at	string	"0001-01-01T00:00:00Z"	No	Show file versions as they were at the specified time.
versions	boolean	false	No	Include old versions in directory listings.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/b2 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "<b2-account-id>",
    "key": "<b2-application-key>",
    "hard_delete": true,
    "description": "Backblaze B2 archival"
  }'

TypeScript SDK

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.createB2({
  account: '<b2-account-id>',
  key: '<b2-application-key>',
  hard_delete: true,
  description: 'Backblaze B2 archival'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "b2",
    "vfs_backend_type": "b2",
    "config": {
      "account": "***",
      "key": "***",
      "hard_delete": true,
      "description": "Backblaze B2 archival"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/cloudinary

Connect a Cloudinary backend.

This endpoint takes no parameters.

Request body

Name	Type	Default	Required	Description
cloud_name	string	""	Yes	Cloudinary Environment Name.
api_key	string	""	Yes	Cloudinary API Key.
api_secret	string	""	Yes	Cloudinary API Secret.
adjust_media_files_extensions	boolean	true	No	Adjust media file extensions, since Cloudinary handles them as a file attribute.
description	string	""	No	Description of the remote.
encoding	string	"52543246"	No	The encoding for the backend.
eventually_consistent_delay	integer	0	No	Wait N seconds for eventual consistency.
media_extensions	string	"3ds,3g2,3gp,ai,arw,avi,avif,bmp,bw,cr2,cr3,djvu,dng,eps3,fbx,flif,flv,gif,glb,gltf,hdp,heic,heif,ico,indd,jp2,jpe,jpeg,jpg,jxl,jxr,m2ts,mov,mp4,mpeg,mts,mxf,obj,ogv,pdf,ply,png,psd,svg,tga,tif,tiff,ts,u3ma,usdz,wdp,webm,webp,wmv"	No	Cloudinary supported media extensions.
upload_prefix	string	""	No	API endpoint prefix for environments outside the US.
upload_preset	string	""	No	Upload preset for asset manipulation.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/cloudinary \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud_name": "mycloud",
    "api_key": "<cloudinary-key>",
    "api_secret": "<cloudinary-secret>",
    "description": "Cloudinary media library"
  }'

TypeScript SDK

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.createCloudinary({
  cloud_name: 'mycloud',
  api_key: '<cloudinary-key>',
  api_secret: '<cloudinary-secret>',
  description: 'Cloudinary media library'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "cloudinary",
    "vfs_backend_type": "cloudinary",
    "config": {
      "cloud_name": "mycloud",
      "api_key": "***",
      "api_secret": "***",
      "description": "Cloudinary media library"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

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

Connect a Google Cloud Storage backend (this is not Google Drive).

This endpoint takes no parameters.

Request body

All fields are optional. Provide credentials through a service account (service_account_credentials), OAuth (client_id/client_secret/token), or set anonymous for public bucket access. env_auth accepts only false: runtime credentials are not available.

Name	Type	Default	Required	Description
access_token	string	""	No	Short-lived access token.
anonymous	boolean	false	No	Access public buckets and objects without credentials.
auth_url	string	""	No	Auth server URL.
bucket_acl	string (enum: authenticatedRead, private, projectPrivate, publicRead, publicReadWrite)	""	No	Access Control List for new buckets.
bucket_policy_only	boolean	false	No	Use bucket-level IAM policies for access checks.
client_credentials	boolean	false	No	Use the OAuth2 client credentials flow.
client_id	string	""	No	OAuth Client Id.
client_secret	string	""	No	OAuth Client Secret.
decompress	boolean	false	No	Decompress gzip-encoded objects on download.
description	string	""	No	Description of the remote.
directory_markers	boolean	false	No	Upload empty objects ending with / for new directories.
encoding	string	"50348034"	No	The encoding for the backend.
endpoint	string	""	No	Endpoint for the service.
env_auth	boolean (enum: false)	false	No	Get GCP IAM credentials from runtime.
location	string (enum: many regions)	""	No	Location for newly created buckets.
no_check_bucket	boolean	false	No	Don’t check that the bucket exists or create it.
object_acl	string (enum: authenticatedRead, bucketOwnerFullControl, bucketOwnerRead, private, projectPrivate, publicRead)	""	No	Access Control List for new objects.
project_number	string	""	No	Project number for bucket operations.
service_account_credentials	string	""	No	Service Account Credentials JSON blob.
storage_class	string (enum: "", MULTI_REGIONAL, REGIONAL, NEARLINE, COLDLINE, ARCHIVE, DURABLE_REDUCED_AVAILABILITY)	""	No	Storage class for new objects.
token	string	""	No	OAuth Access Token as a JSON blob.
token_url	string	""	No	Token server URL.
user_project	string	""	No	User project for requester-pays buckets.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/google-cloud-storage \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_credentials": "<gcp-sa-json>",
    "project_number": "123456789012",
    "location": "us-central1",
    "storage_class": "REGIONAL",
    "description": "GCS regional bucket"
  }'

TypeScript SDK

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.createGoogleCloudStorage({
  service_account_credentials: '<gcp-sa-json>',
  project_number: '123456789012',
  location: 'us-central1',
  storage_class: 'REGIONAL',
  description: 'GCS regional bucket'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "google-cloud-storage",
    "vfs_backend_type": "google cloud storage",
    "config": {
      "service_account_credentials": "***",
      "project_number": "123456789012",
      "location": "us-central1",
      "storage_class": "REGIONAL",
      "description": "GCS regional bucket"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/imagekit

Connect an ImageKit.io backend.

This endpoint takes no parameters.

Request body

Name	Type	Default	Required	Description
endpoint	string	""	Yes	ImageKit.io URL endpoint from the developer dashboard.
public_key	string	""	Yes	ImageKit.io public key.
private_key	string	""	Yes	ImageKit.io private key.
description	string	""	No	Description of the remote.
encoding	string	"117553486"	No	The encoding for the backend.
only_signed	boolean	false	No	Set true if your dashboard restricts unsigned image URLs.
upload_tags	string	""	No	Tags added to uploaded files (e.g. "tag1,tag2").
versions	boolean	false	No	Include old versions in directory listings.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/imagekit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://ik.imagekit.io/myid",
    "public_key": "<imagekit-public>",
    "private_key": "<imagekit-private>",
    "description": "ImageKit CDN"
  }'

TypeScript SDK

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.createImagekit({
  endpoint: 'https://ik.imagekit.io/myid',
  public_key: '<imagekit-public>',
  private_key: '<imagekit-private>',
  description: 'ImageKit CDN'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "imagekit",
    "vfs_backend_type": "imagekit",
    "config": {
      "endpoint": "https://ik.imagekit.io/myid",
      "public_key": "<imagekit-public>",
      "private_key": "***",
      "description": "ImageKit CDN"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/internetarchive

Connect an Internet Archive backend.

This endpoint takes no parameters.

Request body

Leave access_key_id and secret_access_key blank for anonymous access. Defaults for endpoint and front_endpoint point at the standard Internet Archive hosts.

Name	Type	Default	Required	Description
access_key_id	string	""	No	IAS3 Access Key.
description	string	""	No	Description of the remote.
disable_checksum	boolean	true	No	Don’t ask the server to verify an MD5 checksum.
encoding	string	"50446342"	No	The encoding for the backend.
endpoint	string	"https://s3.us.archive.org"	No	IAS3 endpoint.
front_endpoint	string	"https://archive.org"	No	Host of the Internet Archive frontend.
item_derive	boolean	true	No	Whether to trigger derive on the IA item on upload.
item_metadata	string	""	No	Metadata for the IA item in key=value form (the x-archive-meta- prefix is added automatically).
secret_access_key	string	""	No	IAS3 Secret Key (password).
wait_archive	integer	0	No	Timeout for archive processing tasks, in seconds.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.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>",
    "wait_archive": 600,
    "description": "Internet Archive archival"
  }'

TypeScript SDK

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.createInternetarchive({
  access_key_id: '<ia-access-key>',
  secret_access_key: '<ia-secret-key>',
  wait_archive: 600,
  description: 'Internet Archive archival'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "internetarchive",
    "vfs_backend_type": "internetarchive",
    "config": {
      "access_key_id": "***",
      "secret_access_key": "***",
      "wait_archive": 600,
      "description": "Internet Archive archival"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/netstorage

Connect an Akamai NetStorage backend.

This endpoint takes no parameters.

Request body

Name	Type	Default	Required	Description
host	string	""	Yes	Domain and internal path of the NetStorage host (<domain>/<internal folders>).
account	string	""	Yes	NetStorage account name.
secret	string (password)	""	Yes	NetStorage account secret/G2O key.
description	string	""	No	Description of the remote.
protocol	string (enum: http, https)	"https"	No	Select HTTP or HTTPS protocol.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/netstorage \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "my-ns.host.net/path",
    "account": "<netstorage-account>",
    "secret": "<netstorage-secret>",
    "description": "Akamai NetStorage"
  }'

TypeScript SDK

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.createNetstorage({
  host: 'my-ns.host.net/path',
  account: '<netstorage-account>',
  secret: '<netstorage-secret>',
  description: 'Akamai NetStorage'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "netstorage",
    "vfs_backend_type": "netstorage",
    "config": {
      "host": "my-ns.host.net/path",
      "account": "<netstorage-account>",
      "secret": "***",
      "description": "Akamai NetStorage"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/oracleobjectstorage

Connect an Oracle Cloud Infrastructure Object Storage backend.

This endpoint takes no parameters.

Request body

Name	Type	Default	Required	Description
provider	string (enum: no_auth)	"no_auth"	Yes	OCI authentication provider.
namespace	string	""	Yes	Object storage namespace.
region	string	""	Yes	Object storage region.
attempt_resume_upload	boolean	false	No	Attempt to resume a previously started multipart upload.
chunk_size	string	"5242880"	No	Chunk size for multipart uploads, in bytes.
compartment	string	""	No	Compartment OCID (needed only to list buckets).
copy_cutoff	string	"4999610368"	No	Cutoff for switching to multipart copy.
copy_timeout	integer	60	No	Timeout for copy operations, in seconds.
decompress	boolean	false	No	Decompress gzip-encoded objects on download.
description	string	""	No	Description of the remote.
disable_checksum	boolean	false	No	Don’t store MD5 checksum with object metadata.
encoding	string	"50331650"	No	The encoding for the backend.
endpoint	string	""	No	Endpoint for the Object Storage API.
leave_parts_on_error	boolean	false	No	Avoid calling abort upload on failure.
max_upload_parts	integer	10000	No	Maximum number of parts in a multipart upload.
no_check_bucket	boolean	false	No	Don’t check that the bucket exists or create it.
sse_customer_algorithm	string (enum: "", AES256)	""	No	SSE-C encryption algorithm.
sse_customer_key	string	""	No	Base64-encoded SSE-C encryption key.
sse_customer_key_sha256	string	""	No	Base64-encoded SHA256 hash of the SSE-C encryption key.
sse_kms_key_id	string	""	No	OCID of the master encryption key in vault.
storage_tier	string (enum: Standard, InfrequentAccess, Archive)	"Standard"	No	Storage class for new objects.
upload_concurrency	integer	10	No	Concurrency for multipart uploads.
upload_cutoff	string	"209715200"	No	Cutoff for switching to chunked upload.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/oracleobjectstorage \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "no_auth",
    "namespace": "<object-storage-namespace>",
    "region": "us-ashburn-1",
    "compartment": "<compartment-ocid>",
    "storage_tier": "InfrequentAccess",
    "description": "Oracle OCI bucket"
  }'

TypeScript SDK

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.createOracleobjectstorage({
  provider: 'no_auth',
  namespace: '<object-storage-namespace>',
  region: 'us-ashburn-1',
  compartment: '<compartment-ocid>',
  storage_tier: 'InfrequentAccess',
  description: 'Oracle OCI bucket'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "oracleobjectstorage",
    "vfs_backend_type": "oracleobjectstorage",
    "config": {
      "provider": "no_auth",
      "namespace": "<object-storage-namespace>",
      "region": "us-ashburn-1",
      "compartment": "<compartment-ocid>",
      "storage_tier": "InfrequentAccess",
      "description": "Oracle OCI bucket"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/qingstor

Connect a QingCloud Object Storage backend.

This endpoint takes no parameters.

Request body

Leave access_key_id and secret_access_key blank for anonymous access. env_auth accepts only false: runtime credentials are not available.

Name	Type	Default	Required	Description
access_key_id	string	""	No	QingStor Access Key ID.
chunk_size	string	"4194304"	No	Chunk size for multipart uploads, in bytes.
connection_retries	integer	3	No	Number of connection retries.
description	string	""	No	Description of the remote.
encoding	string	"16842754"	No	The encoding for the backend.
endpoint	string	""	No	Endpoint URL for the QingStor API.
env_auth	boolean (enum: false)	false	No	Get QingStor credentials from runtime.
secret_access_key	string	""	No	QingStor Secret Access Key (password).
upload_concurrency	integer	1	No	Concurrency for multipart uploads.
upload_cutoff	string	"209715200"	No	Cutoff for switching to chunked upload.
zone	string (enum: pek3a, sh1a, gd2a)	""	No	Zone to connect to (default pek3a).

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.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",
    "description": "QingStor archive"
  }'

TypeScript SDK

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.createQingstor({
  access_key_id: '<qingstor-access-key>',
  secret_access_key: '<qingstor-secret-key>',
  zone: 'pek3a',
  description: 'QingStor archive'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "qingstor",
    "vfs_backend_type": "qingstor",
    "config": {
      "access_key_id": "***",
      "secret_access_key": "***",
      "zone": "pek3a",
      "description": "QingStor archive"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

POST /api/v1/backends/s3

Connect an Amazon S3 or S3-compliant backend (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, Storj, Synology, TencentCOS, Wasabi, Qiniu, and others).

This endpoint takes no parameters.

Tip

For AWS, leave endpoint blank and set provider: "AWS". The fixed endpoint enum lists common S3 clones, so picking a value from the enum tells Hoody which clone you are using and applies the matching defaults.

Request body

Name	Type	Default	Required	Description
endpoint	string (enum: S3 clone hosts)	""	No	Endpoint for the S3 API. Required for S3 clones; leave blank for AWS.
access_key_id	string	""	No	AWS Access Key ID.
acl	string (enum: private, public-read, public-read-write, authenticated-read, bucket-owner-read, bucket-owner-full-control, default)	""	No	Canned ACL for new buckets and stored objects.
bucket_acl	string (enum: private, public-read, public-read-write, authenticated-read)	""	No	Canned ACL for newly created buckets.
bucket_object_lock_enabled	boolean	false	No	Enable Object Lock when creating new buckets.
bypass_governance_retention	boolean	false	No	Allow deleting or modifying objects locked with GOVERNANCE mode.
chunk_size	string	"5242880"	No	Chunk size for multipart uploads, in bytes.
copy_cutoff	string	"4999610368"	No	Cutoff for switching to multipart copy.
decompress	boolean	false	No	Decompress gzip-encoded objects on download.
description	string	""	No	Description of the remote.
directory_bucket	boolean	false	No	Enable AWS Directory Buckets.
directory_markers	boolean	false	No	Upload empty objects ending with / for new directories.
disable_checksum	boolean	false	No	Don’t store MD5 checksum with object metadata.
disable_http2	boolean	false	No	Disable HTTP/2 for S3 backends.
download_url	string	""	No	Custom endpoint for downloads (e.g. a CloudFront URL).
encoding	string	"50331650"	No	The encoding for the backend.
env_auth	boolean (enum: false)	false	No	Get AWS credentials from runtime.
force_path_style	boolean	true	No	Use path-style access (false for virtual hosted style).
ibm_api_key	string	""	No	IBM API Key to obtain IAM token.
ibm_iam_endpoint	string	""	No	IBM IAM endpoint.
ibm_resource_instance_id	string	""	No	IBM service instance id.
leave_parts_on_error	boolean	false	No	Avoid calling abort upload on failure.
list_chunk	integer	1000	No	Size of listing chunk (MaxKeys).
list_url_encode	string	"unset"	No	Whether to URL-encode listings (true, false, or unset).
list_version	integer	0	No	ListObjects version (0 for auto, 1, or 2).
list_versions_oldest_first	string	"unset"	No	Set if the backend returns object versions oldest first.
location_constraint	string	""	No	Location constraint matching the region.
max_upload_parts	integer	10000	No	Maximum number of parts in a multipart upload.
memory_pool_flush_time	integer	60	No	Memory buffer pool flush interval, in seconds (no longer used).
memory_pool_use_mmap	boolean	false	No	Use mmap buffers in internal memory pool (no longer used).
might_gzip	string	"unset"	No	Set if the backend might gzip objects.
no_check_bucket	boolean	false	No	Don’t check that the bucket exists or create it.
no_head	boolean	false	No	Don’t HEAD uploaded objects to check integrity.
no_head_object	boolean	false	No	Don’t do HEAD before GET when getting objects.
no_system_metadata	boolean	false	No	Suppress setting and reading of system metadata.
object_lock_legal_hold_status	string (enum: ON, OFF, copy)	""	No	Object Lock legal hold status.
object_lock_mode	string (enum: GOVERNANCE, COMPLIANCE, copy)	""	No	Object Lock retention mode.
object_lock_retain_until_date	string (enum: copy, 2030-01-01T00:00:00Z, 365d, 1y)	""	No	Object Lock retention until date.
object_lock_set_after_upload	boolean	false	No	Set Object Lock via separate API calls after upload.
object_lock_supported	string	"unset"	No	Whether the provider supports S3 Object Lock.
provider	string (enum: AWS, Alibaba, ArvanCloud, BizflyCloud, Ceph, ChinaMobile, Cloudflare, Cubbit, DigitalOcean, Dreamhost, Exaba, Fastly, FileLu, FlashBlade, GCS, HCP, Hetzner, HuaweiOBS, IBMCOS, IDrive, ImpossibleCloud, Intercolo, IONOS, Leviia, Liara, Linode, LyveCloud, Magalu, Mega, Minio, Netease, Outscale, OVHcloud, Petabox, Qiniu, Rabata, RackCorp, Hoody-VFS, Scaleway, Scality, SeaweedFS, Selectel, Servercore, SpectraLogic, Storj, Synology, TencentCOS, US3, Wasabi, Zadara, Zata, ZeroServices, Other)	""	No	Choose the S3 provider.
region	string (enum: us-east-1, us-east-2, us-west-1, us-west-2, ca-central-1, eu-west-1, eu-west-2, eu-west-3, eu-north-1, eu-south-1, eu-central-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2, ap-northeast-3, ap-south-1, ap-east-1, sa-east-1, il-central-1, me-south-1, af-south-1, cn-north-1, cn-northwest-1, us-gov-east-1, us-gov-west-1, hn, hcm, "", other-v2-signature, auto, au-east-1, eu-central, jp-central-1, uk-east-1, us-central-1, us-east, us-west, us-west-1, global, ap-southeast, me-central, hel1, fsn1, nbg1, ap-southeast-3, cn-east-3, cn-east-2, cn-north-4, sa-argentina-1, sa-peru-1, na-mexico-1, sa-chile-1, sa-brazil-1, ru-northwest-2, eu-central-2, eu-east-1, de-fra, eu-central-3, eu-central-4, eu-south-2, us-east-2, cloudgouv-eu-west-1, gra, rbx, sbg, eu-west-par, uk, waw, bhs, ca-east-tor, sgp, ap-southeast-syd, ap-south-mum, us-east-va, us-west-or, rbx-archive, me-south-1, cn-east-1, cn-south-1, us-north-1, au, au-nsw, au-qld, au-vic, au-wa, ph, th, hk, mn, kg, id, jp, sg, de, us, nz, nl-ams, fr-par, pl-waw, ru-1, ru-3, ru-7, gis-1, kz-1, uz-2, eu-001, eu-002, us-001, us-002, tw-001, zero-fra1, zero-fra2, zero-eyl1)	""	No	Region to connect to. Leave blank if you are using an S3 clone and you don’t have a region.
requester_pays	boolean	false	No	Enable requester-pays for the S3 bucket.
role_arn	string	""	No	ARN of the IAM role to assume.
role_external_id	string	""	No	External ID for assumed role.
role_session_duration	string	""	No	Session duration for assumed role.
role_session_name	string	""	No	Session name for assumed role.
sdk_log_mode	string	"0"	No	AWS SDK debug log mode (e.g. Signing, Retries, Request).
secret_access_key	string	""	No	AWS Secret Access Key (password).
server_side_encryption	string (enum: "", AES256, aws:kms)	""	No	Server-side encryption algorithm.
session_token	string	""	No	AWS session token.
sign_accept_encoding	string	"unset"	No	Set if Hoody should include Accept-Encoding in the signature.
sse_customer_algorithm	string (enum: "", AES256)	""	No	SSE-C encryption algorithm.
sse_customer_key	string	""	No	SSE-C secret encryption key.
sse_customer_key_base64	string	""	No	SSE-C secret encryption key, base64-encoded.
sse_customer_key_md5	string	""	No	SSE-C encryption key MD5 checksum.
sse_kms_key_id	string (enum: "", arn:aws:kms:us-east-1:*)	""	No	KMS Key ARN.
storage_class	string (enum: "", STANDARD, REDUCED_REDUNDANCY, STANDARD_IA, ONEZONE_IA, GLACIER, DEEP_ARCHIVE, INTELLIGENT_TIERING, GLACIER_IR, EXPRESS_ONEZONE, LINE, ARCHIVE)	""	No	Storage class for new objects.
sts_endpoint	string	""	No	STS endpoint (deprecated).
upload_concurrency	integer	4	No	Concurrency for multipart uploads and copies.
upload_cutoff	string	"209715200"	No	Cutoff for switching to chunked upload.
use_accelerate_endpoint	boolean	false	No	Use the AWS S3 accelerated endpoint.
use_accept_encoding_gzip	string	"unset"	No	Send Accept-Encoding: gzip on download.
use_already_exists	string	"unset"	No	Report BucketAlreadyExists errors on bucket creation.
use_arn_region	boolean	false	No	Enable ARN region support.
use_data_integrity_protections	string	"unset"	No	Use AWS S3 data integrity protections.
use_dual_stack	boolean	false	No	Use the AWS S3 dual-stack endpoint (IPv6).
use_multipart_etag	string	"unset"	No	Use ETag in multipart uploads for verification.
use_multipart_uploads	string	"unset"	No	Whether Hoody should use multipart uploads.
use_presigned_request	boolean	false	No	Use a presigned request for single part uploads.
use_unsigned_payload	string	"unset"	No	Whether to use an unsigned payload in PutObject.
use_x_id	string	"unset"	No	Set if Hoody should add x-id URL parameters.
v2_auth	boolean	false	No	Use v2 authentication (legacy providers).
version_at	string	"0001-01-01T00:00:00Z"	No	Show file versions as they were at the specified time.
version_deleted	boolean	false	No	Show deleted file markers when using versions.
versions	boolean	false	No	Include old versions in directory listings.

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/s3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "Wasabi",
    "endpoint": "s3.wasabisys.com",
    "access_key_id": "<wasabi-access-key>",
    "secret_access_key": "<wasabi-secret-key>",
    "description": "Wasabi hot storage"
  }'

TypeScript SDK

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.createS3({
  provider: 'Wasabi',
  endpoint: 's3.wasabisys.com',
  access_key_id: '<wasabi-access-key>',
  secret_access_key: '<wasabi-secret-key>',
  description: 'Wasabi hot storage'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "s3",
    "vfs_backend_type": "s3",
    "config": {
      "provider": "Wasabi",
      "endpoint": "s3.wasabisys.com",
      "access_key_id": "***",
      "secret_access_key": "***",
      "description": "Wasabi hot storage"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

Decentralized cloud

POST /api/v1/backends/sia

Connect a Sia decentralized cloud backend.

This endpoint takes no parameters.

Request body

Name	Type	Default	Required	Description
api_url	string	n/a	Yes	Sia daemon API URL.
api_password	string (password)	""	No	Sia daemon API password.
description	string	""	No	Description of the remote.
encoding	string	"50436354"	No	The encoding for the backend.
user_agent	string	"Sia-Agent"	No	Siad user agent (must be Sia-Agent by default).

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.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>",
    "description": "Sia decentralized storage"
  }'

TypeScript SDK

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.createSia({
  api_url: 'http://sia.daemon.host:9980',
  api_password: '<sia-api-password>',
  description: 'Sia decentralized storage'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "sia",
    "vfs_backend_type": "sia",
    "config": {
      "api_url": "http://sia.daemon.host:9980",
      "api_password": "***",
      "description": "Sia decentralized storage"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After

OpenStack Swift

POST /api/v1/backends/swift

Connect an OpenStack Swift backend (Rackspace Cloud Files, Blomp Cloud Storage, Memset Memstore, OVH).

This endpoint takes no parameters.

Request body

Name	Type	Default	Required	Description
auth	string (enum: Rackspace, Memset, OVH, AIN endpoints)	""	No	Authentication URL for the server.
auth_version	integer	0	No	Auth version (1, 2, or 3) when the auth URL has no version.
auth_token	string	""	No	Auth Token from alternate authentication.
application_credential_id	string	""	No	Application Credential ID.
application_credential_name	string	""	No	Application Credential Name.
application_credential_secret	string	""	No	Application Credential Secret.
chunk_size	string	"5368709120"	No	Above this size files will be chunked.
description	string	""	No	Description of the remote.
domain	string	""	No	User domain (v3 auth).
encoding	string	"16777218"	No	The encoding for the backend.
endpoint_type	string (enum: public, internal, admin)	"public"	No	Endpoint type from the service catalogue.
env_auth	boolean (enum: false)	false	No	Get Swift credentials from OpenStack environment variables.
fetch_until_empty_page	boolean	false	No	Always fetch while paginating unless an empty page is received.
key	string	""	No	API key or password.
leave_parts_on_error	boolean	false	No	Don’t call abort upload on failure.
no_chunk	boolean	false	No	Don’t chunk files during streaming upload.
no_large_objects	boolean	false	No	Disable support for static and dynamic large objects.
partial_page_fetch_threshold	integer	0	No	Fetch when within this percentage of the page limit.
region	string	""	No	Region name.
storage_policy	string (enum: "", pcs, pca)	""	No	Storage policy for newly created containers.
storage_url	string	""	No	Storage URL.
tenant	string	""	No	Tenant name.
tenant_domain	string	""	No	Tenant domain (v3 auth).
tenant_id	string	""	No	Tenant ID.
use_segments_container	string	"unset"	No	Choose destination for large object segments.
user	string	""	No	Username to log in.
user_id	string	""	No	User ID to log in (v3 auth).

Example request

cURL

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/swift \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "<swift-user>",
    "key": "<swift-password>",
    "auth": "https://auth.cloud.ovh.net/v3",
    "tenant": "<swift-tenant>",
    "region": "GRA1",
    "description": "OVH Object Storage"
  }'

TypeScript SDK

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.createSwift({
  user: '<swift-user>',
  key: '<swift-password>',
  auth: 'https://auth.cloud.ovh.net/v3',
  tenant: '<swift-tenant>',
  region: 'GRA1',
  description: 'OVH Object Storage'
});

Responses

201

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "a1b2c3d4e5f67890",
    "type": "swift",
    "vfs_backend_type": "swift",
    "config": {
      "user": "<swift-user>",
      "key": "***",
      "auth": "https://auth.cloud.ovh.net/v3",
      "tenant": "<swift-tenant>",
      "region": "GRA1",
      "description": "OVH Object Storage"
    },
    "mount_paths": []
  }
}

400

The connection to the backend could not be established. The response indicates the failure reason.

{
  "success": false,
  "error": "Invalid request"
}

409

The service refuses new backend connections while uploads from before a restart are still pending on this backend, or while a delivery of pending uploads to this backend is running. For uploads pending from before a restart, the response carries a Retry-After header with the number of seconds to wait. A conflict with an ongoing delivery carries no Retry-After header; retry after the delivery ends, or stop the delivery.

{
  "success": false,
  "error": "Backend temporarily unavailable"
}

503

The service cannot carry out this request right now. The response carries a Retry-After header with the number of seconds to wait.

{
  "success": false,
  "error": "Service temporarily unavailable",
  "code": "MOUNT_STORAGE_UNAVAILABLE"
}

Error Code	Title	Description	Resolution
MOUNT_STORAGE_UNAVAILABLE	Mounts unavailable	Mounts are unavailable until the server’s storage check passes; retry later. The server’s storage check did not pass (for example, the mount directory and the directory of the backends’ own mounts overlap), so no mount or backend connection can start, and backend file operations are refused. The refusal comes before the mount or backend is looked up, so an unknown id is answered 503, not 404, until the check passes. Existing mounts show the error, and the mount list still answers. Other files are served as usual. Nothing was changed.	Retry after the time given in Retry-After