# Encryption Layer

**Page:** api/files/mount/encryption

[Download Raw Markdown](./api/files/mount/encryption.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Encryption Layer

The encryption layer wraps a remote backend with transparent transforms: the `crypt` overlay encrypts file data and obfuscates filenames using a user-supplied password, and the `compress` overlay reduces payload size with gzip. These endpoints register a new overlay backend that sits in front of an existing remote. Use them when you need at-rest encryption, data reduction, or both stacked together.

Both endpoints return the newly registered backend identifier and its empty mount path list. Once connected, the backend can be mounted into the filesystem like any other remote.

---

### `POST /api/v1/backends/compress`

Connect a compress overlay in front of an existing remote. The remote argument must reference a previously registered backend (for example, a cloud drive or S3 bucket).

This endpoint takes no parameters.

#### Request Body

| Field | 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 (equivalent to `5`) and is recommended. Levels `1`–`9` increase compression at the cost of speed; going past `6` generally offers diminishing returns. `-2` uses Huffman encoding only. `0` disables compression. |
| `mode` | string | No | `"gzip"` | Compression mode. Fixed to `gzip`. |
| `ram_cache_limit` | string | No | `"20971520"` | Files smaller than this limit (bytes) are cached in RAM before upload; larger files are cached on disk. Set this when the underlying remote rejects uploads of unknown size. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/compress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "my-s3:bucket/logs",
    "description": "Gzip-compressed log archive",
    "level": 6,
    "ram_cache_limit": "52428800"
  }'
```


```typescript
await client.files.backends.connectCompress({
  data: {
    remote: "my-s3:bucket/logs",
    description: "Gzip-compressed log archive",
    level: 6,
    ram_cache_limit: "52428800"
  }
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "cmp_8f3a2b1c9d4e5f60",
    "type": "compress",
    "backend_type": "compress",
    "mount_paths": []
  }
}
```



#### Responses



Backend connected successfully.

```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "cmp_8f3a2b1c9d4e5f60",
    "type": "compress",
    "backend_type": "compress",
    "mount_paths": []
  }
}
```


Connection failed. The referenced remote does not exist, the configuration is invalid, or the remote is already wrapped by a compress overlay.

```json
{
  "success": false,
  "error": "Remote 'my-s3:bucket/logs' not found"
}
```



---

### `POST /api/v1/backends/crypt`

Connect a crypt overlay in front of an existing remote. The crypt backend encrypts file data with a user-supplied password, optionally obfuscates filenames and directory names, and can be tuned for compatibility with case-sensitive or length-limited filesystems.

This endpoint takes no parameters.

#### Request Body

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `remote` | string | Yes | `""` | Remote to encrypt or decrypt. Typically `remote:path`, `remote:bucket`, or `remote:` (not recommended). |
| `password` | string | Yes | `""` | Password or passphrase used for encryption. |
| `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"` | Encoding used for the encrypted filename. Choose based on whether the backend is case-sensitive and how it counts filename length. One of `base32`, `base64`, `base32768`. |
| `filename_encryption` | string | No | `"standard"` | Filename encryption mode. One of `standard`, `obfuscate`, `off`. |
| `no_data_encryption` | boolean | No | `false` | When `true`, file contents are stored unencrypted; only filenames are transformed. |
| `pass_bad_blocks` | boolean | No | `false` | Pass bad decryption blocks through as zeros. Recovery-only setting. |
| `password2` | string | No | `""` | Salt passphrase. Optional but recommended; should differ from `password`. |
| `server_side_across_configs` | boolean | No | `false` | Allow server-side operations (for example, copy) to work across different crypt configurations. Deprecated alias of `--server-side-across-configs`. |
| `show_mapping` | boolean | No | `false` | Log the decrypted-to-encrypted filename mapping for every listed file. |
| `strict_names` | boolean | No | `false` | Raise an error when an undecryptable filename is encountered. By default, a NOTICE is logged and listing continues. |
| `suffix` | string | No | `".bin"` | Override the default `.bin` suffix appended to encrypted files. Set to `none` for an empty suffix. |



```bash
curl -X POST https://api.hoody.com/api/v1/backends/crypt \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "my-s3:bucket/private",
    "description": "Encrypted personal archive",
    "password": "correct horse battery staple",
    "password2": "another salt phrase here",
    "filename_encryption": "standard",
    "filename_encoding": "base32",
    "directory_name_encryption": true,
    "suffix": ".bin"
  }'
```


```typescript
await client.files.backends.connectCrypt({
  data: {
    remote: "my-s3:bucket/private",
    description: "Encrypted personal archive",
    password: "correct horse battery staple",
    password2: "another salt phrase here",
    filename_encryption: "standard",
    filename_encoding: "base32",
    directory_name_encryption: true,
    suffix: ".bin"
  }
});
```


```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "cry_2b7e4a91c0f83d65",
    "type": "crypt",
    "backend_type": "crypt",
    "mount_paths": []
  }
}
```



#### Responses



Backend connected successfully.

```json
{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "id": "cry_2b7e4a91c0f83d65",
    "type": "crypt",
    "backend_type": "crypt",
    "mount_paths": []
  }
}
```


Connection failed. Typical causes: missing or empty `password`, unknown `remote`, invalid `filename_encoding`/`filename_encryption` value, or the remote is already wrapped by a crypt overlay.

```json
{
  "success": false,
  "error": "password is required and must be non-empty"
}
```




Stacking overlays is order-sensitive. A compress backend layered on top of a crypt backend is **not** equivalent to a crypt backend layered on top of compress. Encrypt first, then compress the encrypted bytes, unless you have a specific reason to do otherwise.