Encryption Layer

The encryption layer wraps an existing remote with the Hoody crypt or compress overlay backend. Use these endpoints to compose an encrypted or compressed view on top of any already connected remote without modifying the underlying storage.

All endpoints on this page run against the container-scoped files service.

POST /api/v1/backends/compress

Connects a GZIP compression overlay over an existing remote. Useful for shrinking backups or log archives before they are uploaded to another backend.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
description	string	No	""	Description of the remote.
level	integer	No	-1	GZIP compression level. Valid range: from -2 to 9. Generally -1 is recommended. Levels 1 to 9 increase compression at the cost of speed; going past 6 rarely helps. Level -2 uses Huffman encoding only; level 0 turns off compression.
mode	string	No	"gzip"	Compression mode. Always gzip.
ram_cache_limit	string	No	"20971520"	Files smaller than this limit are cached in RAM; larger files are cached on disk. Used when a remote does not allow uploading files of unknown size.
remote	string	Yes	""	Remote to compress.

cURL

curl -X POST "https://myproj-abc123-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/compress" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "remote": "mybackup:/backups",
    "level": 5,
    "mode": "gzip",
    "ram_cache_limit": "20971520",
    "description": "Backups archive on local disk"
  }'

JavaScript SDK

await client.files.backends.connectCompress({
  remote: "mybackup:/backups",
  level: 5,
  mode: "gzip",
  ram_cache_limit: "20971520",
  description: "Backups archive on local disk"
});

Response

201

Backend connected successfully.

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "compress-a1b2c3d4e5",
    "type": "compress",
    "backend_type": "compress",
    "mount_paths": []
  }
}

400

Connection failed.

{
  "success": false,
  "error": "Remote not found: mybackup:/backups"
}

POST /api/v1/backends/crypt

Connects a crypt overlay that encrypts and decrypts an existing remote. The crypt layer controls filename handling, directory-name encryption, optional salt, and recovery behavior.

This endpoint takes no parameters.

Request Body

Field	Type	Required	Default	Description
description	string	No	""	Description of the remote.
directory_name_encryption	boolean	No	true	Encrypt directory names. Has no effect when filename_encryption is off.
filename_encoding	string	No	"base32"	How encrypted filenames are encoded as text. One of base32, base64, base32768.
filename_encryption	string	No	"standard"	Filename encryption mode. One of standard, obfuscate, off.
no_data_encryption	boolean	No	false	Encrypt file data. Set to true to leave file bodies unencrypted.
pass_bad_blocks	boolean	No	false	Recovery only. Pass bad blocks through as zeros so a corrupted file can still be partially recovered.
password	string	Yes	""	Password or pass phrase used to derive the encryption key.
password2	string	No	""	Password or pass phrase used as salt. Recommended and should differ from password.
remote	string	Yes	""	Remote to encrypt or decrypt, for example myremote:path/to/dir or myremote:bucket.
server_side_across_configs	boolean	No	false	Allow server-side operations (such as copy) across different crypt configs. Useful when migrating between filename encryption schemes without re-uploading data.
show_mapping	boolean	No	false	Log a mapping line for each file listing showing the decrypted and encrypted names. Useful for debugging.
strict_names	boolean	No	false	Raise an error when crypt encounters a filename that cannot be decrypted. By default, Hoody logs a NOTICE and continues.
suffix	string	No	".bin"	Suffix appended to encrypted filenames. Set to none for no suffix.

cURL

curl -X POST "https://myproj-abc123-files-1.eu-west-1.containers.hoody.icu/api/v1/backends/crypt" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "remote": "mybackup:/encrypted",
    "password": "s3cret-passphrase",
    "password2": "s4lt-passphrase",
    "filename_encryption": "standard",
    "filename_encoding": "base32",
    "directory_name_encryption": true,
    "suffix": ".bin",
    "description": "Encrypted backups vault"
  }'

JavaScript SDK

await client.files.backends.connectCrypt({
  remote: "mybackup:/encrypted",
  password: "s3cret-passphrase",
  password2: "s4lt-passphrase",
  filename_encryption: "standard",
  filename_encoding: "base32",
  directory_name_encryption: true,
  suffix: ".bin",
  description: "Encrypted backups vault"
});

Response

201

Backend connected successfully.

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "crypt-f6g7h8i9j0",
    "type": "crypt",
    "backend_type": "crypt",
    "mount_paths": []
  }
}

400

Connection failed.

{
  "success": false,
  "error": "Password is required"
}

Tip

The crypt and compress backends compose with any other connected remote. Mount a crypt on top of an S3 remote, or a compress layer on top of a local disk remote, by passing the desired underlying remote string in the remote field of the new overlay.