Encryption Layer

The Encryption Layer endpoints wrap an existing remote with overlays that add compression or transparent encryption. Use the compress backend to reduce storage size on remotes that don’t support it natively, and the crypt backend to encrypt filenames and file contents with a passphrase before they reach the underlying remote. Both endpoints return a new backend identifier that can subsequently be mounted and used like any other storage backend.

Compress Backend

POST /api/v1/backends/compress

Compress a remote using the gzip compression overlay. The compressed backend transparently decompresses files on read and recompresses them on write.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
remote	string	Yes	""	Remote to compress.
description	string	No	""	Description of the remote.
level	integer	No	-1	GZIP compression level (-2 to 9). -1 is the default and is equivalent to level 5. Levels 1 to 9 increase compression at the cost of speed. Level -2 uses Huffman encoding only. Level 0 turns off compression.
mode	string	No	"gzip"	Compression mode. Allowed: gzip.
ram_cache_limit	string	No	"20971520"	Files smaller than this limit are cached in RAM, files larger than this limit are cached on disk. Used when the remote does not allow upload of files with unknown size.

Tip

A compression level of -1 (equivalent to 5) offers the best balance between speed and size for most workloads. Going past 6 generally produces very little size improvement.

Response

201

Backend connected successfully.

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

400

Connection failed.

{
  "success": false,
  "error": "Remote 'myremote:backup' not found"
}

Code Examples

cURL

curl -X POST https://api.hoody.com/api/v1/backends/compress \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:backup",
    "description": "Compressed backup of media",
    "level": 5,
    "mode": "gzip",
    "ram_cache_limit": "20971520"
  }'

JavaScript

const result = await client.files.backends.connectCompress({
  remote: "myremote:backup",
  description: "Compressed backup of media",
  level: 5,
  mode: "gzip",
  ram_cache_limit: "20971520"
});

Crypt Backend

POST /api/v1/backends/crypt

Encrypt and decrypt a remote using the crypt overlay. Filenames and file contents are encrypted with the supplied passphrase before being stored on the underlying remote and decrypted transparently on read.

This endpoint takes no parameters.

Request Body

Name	Type	Required	Default	Description
remote	string	Yes	""	Remote to encrypt/decrypt. Should normally contain a : and a path, for example myremote:path/to/dir or myremote:bucket.
password	string	Yes	""	Password or pass phrase for encryption.
password2	string	No	""	Password or pass phrase for salt. Optional but recommended. Should be different from the primary password.
description	string	No	""	Description of the remote.
directory_name_encryption	boolean	No	true	Whether to encrypt directory names or leave them intact. Has no effect when filename_encryption is off. Allowed: true, false.
filename_encoding	string	No	"base32"	How to encode the encrypted filename to text. Allowed: base32, base64, base32768.
filename_encryption	string	No	"standard"	How to encrypt the filenames. Allowed: standard, obfuscate, off.
no_data_encryption	boolean	No	false	Whether to encrypt file data or leave it unencrypted. Allowed: true, false.
pass_bad_blocks	boolean	No	false	Pass bad blocks through as all 0. Should not be set in normal operation; only useful when recovering an encrypted file with errors.
server_side_across_configs	boolean	No	false	Allow server-side operations (e.g. copy) to work across different crypt configs. Useful for migrating between filename encryption schemes without re-uploading data.
show_mapping	boolean	No	false	Log how each decrypted filename maps to its encrypted form. Useful for debugging.
strict_names	boolean	No	false	Raise an error when crypt encounters a filename that cannot be decrypted (e.g. unencrypted files mixed into the remote).
suffix	string	No	".bin"	Override the default suffix appended to encrypted filenames. Set to none for an empty suffix.

Caution

The encryption password is required to decrypt data. If the password is lost, the encrypted data on the remote cannot be recovered. Store it in a secure password manager before mounting the crypt backend.

Note

Set password2 to a value distinct from password to harden the salt. The two-passphrase configuration is recommended for production deployments.

Response

201

Backend connected successfully.

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

400

Connection failed.

{
  "success": false,
  "error": "Password is required for crypt backend"
}

Code Examples

cURL

curl -X POST https://api.hoody.com/api/v1/backends/crypt \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:encrypted",
    "password": "correct-horse-battery-staple",
    "password2": "another-strong-passphrase",
    "description": "Encrypted sensitive documents",
    "filename_encryption": "standard",
    "filename_encoding": "base32",
    "directory_name_encryption": true,
    "suffix": ".bin"
  }'

JavaScript

const result = await client.files.backends.connectCrypt({
  remote: "myremote:encrypted",
  password: "correct-horse-battery-staple",
  password2: "another-strong-passphrase",
  description: "Encrypted sensitive documents",
  filename_encryption: "standard",
  filename_encoding: "base32",
  directory_name_encryption: true,
  suffix: ".bin"
});