<!--
hoody-files Subskill (http)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-31T17:24:15.305Z
Model: mimo-v2.5-pro + fixer:z-ai/glm-5.1
Mode: http


Tokens: 21938

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-files Subskill

## Overview

**Service**: hoody-files
**Purpose**: Universal file access across local storage and 60+ cloud providers. Every file path is a URL.
**Total Endpoints**: 117
**Base URL Pattern**:

```
https://{projectId}-{containerId}-files-{serviceId}.{node}.containers.hoody.icu
```

### When to Use hoody-files

Use hoody-files when your agent needs to:

- **Read or write files** on local container filesystem or remote cloud storage
- **Manage cloud storage backends**
- **Extract or create archives**
- **Search files** using glob patterns or grep with regex
- **Process images** on-the-fly
- **Mount remote storage** as persistent FUSE filesystems
- **Track file mutations** via the journal system
- **Download files** from remote URLs to the server

### Authentication Model

hoody-files runs as a Hoody Kit service inside your project container. Authentication is handled at the proxy layer:

- All requests must go through the Hoody Proxy routing system
- The proxy validates your Hoody API token before forwarding to the service
- No separate API key is needed for hoody-files itself
- Backend connections (S3 keys, OAuth tokens, etc.) are stored encrypted within the service

### How It Fits Into Hoody Philosophy

hoody-files integrates [rclone](https://rclone.org) to expose 60+ storage backends through a unified HTTP interface. The service translates REST requests into rclone operations, and Hoody's proxy layer routes requests to the appropriate backend. This architecture allows accessing local and remote files through the same URL patterns without provider-specific SDKs.

### Base URL Setup

Define the base URL once for all examples in this document:

```
# Replace with your actual project/container/service values
export FILES_BASE="https://{projectId}-{containerId}-files-{serviceId}.{node}.containers.hoody.icu"
```

---

## Core Resource Workflows

### 1. File Operations (v1 API)

The `/api/v1/files/` endpoints provide the primary interface for all file CRUD operations. These work against local storage and any connected backend.

#### 1.1 List Directory Contents

```
curl -s -X GET "${FILES_BASE}/api/v1/files/documents" \
  -H "Content-Type: application/json"
```

Response returns JSON array of file metadata:

```
[
  {
    "name": "report.pdf",
    "type": "file",
    "size": 245760,
    "modTime": "2025-01-15T10:30:00Z"
  },
  {
    "name": "images",
    "type": "directory",
    "size": 0,
    "modTime": "2025-01-14T08:00:00Z"
  }
]
```

#### 1.2 Get File Metadata (stat)

```
curl -s -X GET "${FILES_BASE}/api/v1/files/stat/documents/report.pdf" \
  -H "Content-Type: application/json"
```

Response:

```
{
  "name": "report.pdf",
  "type": "file",
  "size": 245760,
  "modTime": "2025-01-15T10:30:00Z",
  "permissions": "-rw-r--r--",
  "owner": "1000",
  "group": "1000",
  "isSymlink": false
}
```

#### 1.3 Download a File

```
curl -s -X GET "${FILES_BASE}/api/v1/files/documents/report.pdf" \
  -o report.pdf
```

#### 1.4 Upload a File

```
curl -s -X PUT "${FILES_BASE}/api/v1/files/documents/report.pdf" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./local-report.pdf
```

#### 1.5 Append to a File

```
curl -s -X PUT "${FILES_BASE}/api/v1/files/append/logs/app.log" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./new-entries.log
```

Creates the file if it does not exist. Auto-creates parent directories.

#### 1.6 Create Directory

```
curl -s -X POST "${FILES_BASE}/api/v1/files/documents/new-folder" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "mkdir"
  }'
```

#### 1.7 Delete File or Directory

```
curl -s -X DELETE "${FILES_BASE}/api/v1/files/documents/old-report.pdf" \
  -H "Content-Type: application/json"
```

#### 1.8 Copy File

```
curl -s -X POST "${FILES_BASE}/api/v1/files/copy/documents/report.pdf" \
  -H "Content-Type: application/json" \
  -d '{
    "dest": "backups/report-copy.pdf"
  }'
```

Auto-creates parent directories at destination. Use `?overwrite=true` to replace existing destination.

#### 1.9 Move / Rename File

```
curl -s -X POST "${FILES_BASE}/api/v1/files/move/documents/report.pdf" \
  -H "Content-Type: application/json" \
  -d '{
    "dest": "archive/2025/report.pdf"
  }'
```

Works across directories. Auto-creates parent directories at destination. Requires both upload and delete permissions.

#### 1.10 Change Permissions (Unix)

```
curl -s -X PATCH "${FILES_BASE}/api/v1/files/chmod/scripts/deploy.sh?chmod=755" \
  -H "Content-Type: application/json"
```

#### 1.11 Change Ownership (Unix)

```
curl -s -X PATCH "${FILES_BASE}/api/v1/files/chown/data/config.json?chown=www-data:www-data" \
  -H "Content-Type: application/json"
```

#### 1.12 Modify File Properties (REST v1)

PATCH supports multiple operations via query parameters or JSON body:

```
# Rename via JSON body
curl -s -X PATCH "${FILES_BASE}/api/v1/files/documents/report.pdf" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "final-report.pdf"
  }'
```

```
# Move to different directory via JSON body
curl -s -X PATCH "${FILES_BASE}/api/v1/files/documents/report.pdf" \
  -H "Content-Type: application/json" \
  -d '{
    "move_to": "archive/"
  }'
```

#### 1.13 Resolve Real Path

```
curl -s -X GET "${FILES_BASE}/api/v1/files/realpath/current-link" \
  -H "Content-Type: application/json"
```

Follows all symbolic links and resolves `.` / `..` segments to canonical absolute form.

#### 1.14 Search Files with Glob

```
# Find all TypeScript files recursively
curl -s -X GET "${FILES_BASE}/api/v1/files/glob/src/**/*.{ts,tsx}" \
  -H "Content-Type: application/json"
```

Supports recursive patterns (`**/*.rs`), brace expansion (`{ts,tsx}`), character classes (`[a-z]`), and standard wildcards (`*`). Returns file metadata sorted.

#### 1.15 Search File Contents with Grep

```
# Search for TODO comments across all source files
curl -s -X GET "${FILES_BASE}/api/v1/files/grep/src?pattern=TODO&glob=*.ts" \
  -H "Content-Type: application/json"
```

Powered by ripgrep engine with `.gitignore` support, binary file detection, and configurable limits. Returns matching lines with optional context.

#### 1.16 Download from Remote URL to Server

```
curl -s -X GET "${FILES_BASE}/downloads?url=https://example.com/file.zip" \
  -H "Content-Type: application/json"
```

#### 1.17 Check Download Progress

```
curl -s -X GET "${FILES_BASE}/api/v1/downloads" \
  -H "Content-Type: application/json"
```

---

### 2. File Operations (Root-Level / Legacy API)

These endpoints provide simpler access patterns. They are the original hoody-files interface and remain fully supported.

#### 2.1 List Directory (Root-Level)

```
curl -s -X GET "${FILES_BASE}/documents" \
  -H "Content-Type: application/json"
```

Returns directory listing in HTML or JSON format. For file paths, use `?download` to force `Content-Disposition: attachment`.

#### 2.2 Upload File (Root-Level)

```
curl -s -X PUT "${FILES_BASE}/documents/report.pdf" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./report.pdf
```

Creates new files or overwrites existing ones.

#### 2.3 Touch File

```
curl -s -X PUT "${FILES_BASE}/documents/new-file.txt?touch" \
  -H "Content-Type: application/json"
```

Creates an empty file if it does not exist, or updates the modification time if it does. Cannot be used on directories.

#### 2.4 Patch File (Root-Level)

```
# Rename file
curl -s -X PATCH "${FILES_BASE}/documents/report.pdf" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "final-report.pdf"
  }'
```

Supports: resumable upload, append to files, change file permissions (Unix only), change file ownership (Unix only), rename file or directory.

#### 2.5 Delete File (Root-Level)

```
curl -s -X DELETE "${FILES_BASE}/documents/old-file.txt" \
  -H "Content-Type: application/json"
```

Permanently delete a file or directory.

#### 2.6 Get File Metadata (HEAD)

```
curl -s -I -X HEAD "${FILES_BASE}/documents/report.pdf" \
  -H "Content-Type: application/json"
```

#### 2.7 WebDAV Options Discovery

```
curl -s -X OPTIONS "${FILES_BASE}/documents/" \
  -H "Content-Type: application/json"
```

Returns supported HTTP methods and WebDAV capabilities in the `Allow` header. Used by WebDAV clients for capability discovery.

#### 2.8 Search Files (Root-Level)

```
# Search with HTML response
curl -s -X GET "${FILES_BASE}/documents?q=report" \
  -H "Content-Type: application/json"

# Search with JSON response
curl -s -X GET "${FILES_BASE}/documents?q=report&json=true" \
  -H "Content-Type: application/json"
```

#### 2.9 Download File (Force Attachment)

```
curl -s -X GET "${FILES_BASE}/documents/report.pdf?download" \
  -H "Content-Type: application/json" \
  -o report.pdf
```

#### 2.10 Create ZIP Archive of Directory

```
curl -s -X GET "${FILES_BASE}/documents?zip" \
  -H "Content-Type: application/json" \
  -o documents.zip
```

Create and download directory as ZIP archive.

#### 2.11 Image Thumbnail Generation

```
# Generate thumbnail with auto-detected format
curl -s -X GET "${FILES_BASE}/images/photo.jpg?thumbnail" \
  -H "Content-Type: application/json" \
  -o photo-thumb.jpg
```

On-the-fly image processing with format conversion, resizing, and effects. Supports JPEG, PNG, WebP, GIF, BMP input/output. Works for both local files and all 60+ remote cloud storage backends.

#### 2.12 Remote File Access (Protocol-Based)

Access files from remote servers using protocol-specific query parameters:

```
# Access Git repository files
curl -s -X GET "${FILES_BASE}/my-repo/src/main.rs?type=git" \
  -H "Content-Type: application/json"

# Access S3 bucket files
curl -s -X GET "${FILES_BASE}/my-bucket/path/to/file?type=s3" \
  -H "Content-Type: application/json"

# Access SSH server files
curl -s -X GET "${FILES_BASE}/remote-server/path/to/file?type=ssh" \
  -H "Content-Type: application/json"

# Access WebDAV server files
curl -s -X GET "${FILES_BASE}/nextcloud/path/to/file?type=webdav" \
  -H "Content-Type: application/json"

# Access FTP server files
curl -s -X GET "${FILES_BASE}/ftp-server/path/to/file?type=ftp" \
  -H "Content-Type: application/json"
```

#### 2.13 Upload to SSH Server

```
curl -s -X PUT "${FILES_BASE}/remote-server/path/to/file?type=ssh" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./local-file.txt
```

---

### 3. Archive Operations

#### 3.1 Extract Archive

```
# Extract entire archive
curl -s -X GET "${FILES_BASE}/backups/archive.tar.gz?extract" \
  -H "Content-Type: application/json"

# Extract specific files matching path
curl -s -X GET "${FILES_BASE}/backups/archive.tar.gz?extract=src/main.rs" \
  -H "Content-Type: application/json"
```

Extract ZIP, TAR, or compressed TAR archives to destination directory. Empty `?extract` extracts all; `?extract=<path>` selectively extracts matching entries.

#### 3.2 Extract Single File from Archive

```
curl -s -X GET "${FILES_BASE}/backups/archive.tar.gz?extract_file=config.json" \
  -H "Content-Type: application/json"
```

Only the specified entry (and its children if a directory) is extracted, leaving other archive contents untouched.

#### 3.3 Preview Archive Contents

```
# List all entries as JSON
curl -s -X GET "${FILES_BASE}/backups/archive.zip?preview" \
  -H "Content-Type: application/json"

# Read specific file from archive
curl -s -X GET "${FILES_BASE}/backups/archive.zip?preview=README.md" \
  -H "Content-Type: application/json"
```

#### 3.4 View Single File from Archive

```
curl -s -X GET "${FILES_BASE}/backups/archive.tar.gz?view_file=data/config.json" \
  -H "Content-Type: application/json" \
  -o config.json
```

Returns the raw file content with auto-detected MIME type. Useful for inspecting files without extracting the entire archive.

#### 3.5 Extraction History

```
# Past extractions (successful and failed)
curl -s -X GET "${FILES_BASE}/?extraction_history" \
  -H "Content-Type: application/json"
```

#### 3.6 Active Extractions

```
# Root-level endpoint
curl -s -X GET "${FILES_BASE}/?extractions" \
  -H "Content-Type: application/json"

# v1 API endpoint
curl -s -X GET "${FILES_BASE}/api/v1/extractions" \
  -H "Content-Type: application/json"
```

#### 3.7 Download History

```
curl -s -X GET "${FILES_BASE}/?download_history" \
  -H "Content-Type: application/json"
```

---

### 4. Backend Management

Backends are connections to external storage providers. hoody-files supports 60+ cloud storage backends through its rclone integration. Each backend is assigned an ID and can be managed independently.

#### 4.1 List All Backends

```
curl -s -X GET "${FILES_BASE}/api/v1/backends" \
  -H "Content-Type: application/json"
```

Response:

```
[
  {
    "id": "my-s3-bucket",
    "type": "s3",
    "status": "connected"
  },
  {
    "id": "personal-drive",
    "type": "drive",
    "status": "connected"
  }
]
```

#### 4.2 Get Backend Details

```
curl -s -X GET "${FILES_BASE}/api/v1/backends/my-s3-bucket" \
  -H "Content-Type: application/json"
```

#### 4.3 Test Backend Connection

```
curl -s -X GET "${FILES_BASE}/api/v1/backends/my-s3-bucket/test" \
  -H "Content-Type: application/json"
```

Returns connection status to verify the backend is reachable and credentials are valid.

#### 4.4 Update Backend Credentials

```
curl -s -X PUT "${FILES_BASE}/api/v1/backends/my-s3-bucket" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "new-access-key-id",
    "secret": "new-secret-access-key"
  }'
```

Rotate credentials (passwords, tokens, OAuth refresh tokens, S3 keys, passphrases) for an existing backend connection. Identity fields (host, user, port, type) cannot be changed; disconnect and reconnect to change those.

#### 4.5 Delete Backend

```
curl -s -X DELETE "${FILES_BASE}/api/v1/backends/my-s3-bucket" \
  -H "Content-Type: application/json"
```

#### 4.6 Connect S3 Backend

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/s3" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "AWS",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1",
    "endpoint": ""
  }'
```

Amazon S3 Compliant Storage Providers including AWS, Alibaba, ArvanCloud, Ceph, ChinaMobile, Cloudflare, DigitalOcean, Dreamhost, GCS, HuaweiOBS, IBMCOS, IDrive, IONOS, LyveCloud, Leviia, Liara, Linode, and many more.

#### 4.7 Connect Google Cloud Storage Backend

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/google-cloud-storage" \
  -H "Content-Type: application/json" \
  -d '{
    "project_number": "my-gcs-project",
    "bucket_policy_only": true
  }'
```

Google Cloud Storage (this is not Google Drive).

#### 4.8 Connect Backblaze B2 Backend

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/b2" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "example-account-id",
    "key": "example-application-key"
  }'
```

#### 4.9 Connect Cloudinary Backend

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/cloudinary" \
  -H "Content-Type: application/json" \
  -d '{
    "cloud_name": "my-cloud",
    "api_key": "123456789012345",
    "api_secret": "example-api-secret"
  }'
```

#### 4.10 Connect FTP Backend

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/ftp" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "ftp.example.com",
    "user": "ftpuser",
    "pass": "ftppassword"
  }'
```

#### 4.11 Connect File Fabric Backend

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/filefabric" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mycompany.filefabric.com"
  }'
```

#### 4.12 Connect Utility Backends

**Alias Backend** — Point to another remote or path:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/alias" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:path/to/dir"
  }'
```

Can be `myremote:path/to/dir`, `myremote:`, or `/local/path`.

**Cache Backend** — Add caching layer to another remote:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/cache" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:path/to/dir"
  }'
```

Normally should contain a `:` and a path.

**Chunker Backend** — Transparently chunk/split large files:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/chunker" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:path/to/dir"
  }'
```

**Combine Backend** — Merge several remotes into one:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/combine" \
  -H "Content-Type: application/json" \
  -d '{
    "upstreams": "remote1:path1 remote2:path2"
  }'
```

Upstreams should be in the form `dir=subfolder` pairs.

**Compress Backend** — Add compression to another remote:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/compress" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:path/to/dir"
  }'
```

**Crypt Backend** — Encrypt/decrypt another remote:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/crypt" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:path/to/dir",
    "password": "my-strong-passphrase",
    "password2": "my-secondary-passphrase"
  }'
```

**Hasher Backend** — Better checksums for other remotes:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/hasher" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:path/to/dir"
  }'
```

**Memory Backend** — In-memory object storage system:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/memory" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Union Backend** — Merge contents of several upstream filesystems:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/union" \
  -H "Content-Type: application/json" \
  -d '{
    "upstreams": "remote1:path1 remote2:path2"
  }'
```

#### 4.13 Connect Consumer Cloud Backends

**Google Drive**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/drive" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Dropbox**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/dropbox" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**OneDrive**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/onedrive" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Box**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/box" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Mega**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/mega" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**pCloud**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/pcloud" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**iCloud Drive**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/iclouddrive" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Google Photos**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/google-photos" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**ProtonDrive**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/protondrive" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### 4.14 Connect Enterprise/Protocol Backends

**Azure Blob Storage**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/azureblob" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Azure Files**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/azurefiles" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**SFTP**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/sftp" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**WebDAV**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/webdav" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**SMB/CIFS**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/smb" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**HDFS**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/hdfs" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**HTTP Backend**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/http" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**OpenStack Swift**:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/swift" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Oracle Cloud Infrastructure Object Storage:

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/oracleobjectstorage" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**Storj Decentralized Cloud Storage** (tardigrade is the legacy name; use `storj`):

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/storj" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### 4.15 Connect Additional Cloud Backends

All of the following use the same pattern — POST with provider-specific JSON body:

| Backend | Endpoint | Notes |
|---------|----------|-------|
| Fichier | `/api/v1/backends/fichier` | 1fichier.com |
| Files.com | `/api/v1/backends/filescom` | Enterprise file transfer |
| GoFile | `/api/v1/backends/gofile` | Anonymous file sharing |
| HiDrive | `/api/v1/backends/hidrive` | Strato HiDrive |
| ImageKit | `/api/v1/backends/imagekit` | Image CDN |
| Internet Archive | `/api/v1/backends/internetarchive` | Archive.org |
| Jottacloud | `/api/v1/backends/jottacloud` | Norwegian cloud storage |
| Koofr | `/api/v1/backends/koofr` | Koofr, Digi Storage, and compatible |
| Linkbox | `/api/v1/backends/linkbox` | Linkbox cloud |
| Local | `/api/v1/backends/local` | Local filesystem |
| Mail.ru Cloud | `/api/v1/backends/mailru` | Mail.ru Cloud |
| NetStorage | `/api/v1/backends/netstorage` | Akamai NetStorage |
| OpenDrive | `/api/v1/backends/opendrive` | OpenDrive |
| PikPak | `/api/v1/backends/pikpak` | PikPak cloud |
| Pixeldrain | `/api/v1/backends/pixeldrain` | Pixeldrain file sharing |
| Premiumize.me | `/api/v1/backends/premiumizeme` | Premiumize.me |
| Put.io | `/api/v1/backends/putio` | Put.io |
| QingStor | `/api/v1/backends/qingstor` | QingCloud Object Storage |
| Quatrix | `/api/v1/backends/quatrix` | Maytech Quatrix |
| Seafile | `/api/v1/backends/seafile` | Seafile server |
| ShareFile | `/api/v1/backends/sharefile` | Citrix ShareFile |
| Sia | `/api/v1/backends/sia` | Sia decentralized storage |
| SugarSync | `/api/v1/backends/sugarsync` | SugarSync |
| Uloz.to | `/api/v1/backends/ulozto` | Uloz.to |
| Uptobox | `/api/v1/backends/uptobox` | Uptobox |
| Yandex Disk | `/api/v1/backends/yandex` | Yandex Disk |
| Zoho WorkDrive | `/api/v1/backends/zoho` | Zoho WorkDrive |

```
# Example: Connect Koofr backend
curl -s -X POST "${FILES_BASE}/api/v1/backends/koofr" \
  -H "Content-Type: application/json" \
  -d '{}'
```

---

### 5. Mounts (FUSE Filesystem)

Mounts create persistent FUSE filesystem mounts for connected backends, allowing direct file system access to remote storage. All mounts are automatically persisted and restored on server restart.

#### 5.1 List All Mounts

```
curl -s -X GET "${FILES_BASE}/api/v1/mounts" \
  -H "Content-Type: application/json"
```

Supports filtering by label:

```
curl -s -X GET "${FILES_BASE}/api/v1/mounts?label=production" \
  -H "Content-Type: application/json"
```

#### 5.2 Create Mount

```
curl -s -X POST "${FILES_BASE}/api/v1/mounts" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "my-s3-bucket",
    "mount_point": "/mnt/s3-data",
    "label": "production"
  }'
```

#### 5.3 Get Mount Details

```
curl -s -X GET "${FILES_BASE}/api/v1/mounts/mount-abc123" \
  -H "Content-Type: application/json"
```

#### 5.4 Update Mount Configuration

```
curl -s -X PATCH "${FILES_BASE}/api/v1/mounts/mount-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "cache_settings": {
      "ttl": 300
    }
  }'
```

Allows changing cache settings, buffer sizes, and other VFS parameters.

#### 5.5 Remove Mount

```
curl -s -X DELETE "${FILES_BASE}/api/v1/mounts/mount-abc123" \
  -H "Content-Type: application/json"
```

Removes the mount and disconnects the FUSE filesystem.

---

### 6. Journal System

The journal tracks all file mutations for audit and replay purposes.

#### 6.1 Query Journal Entries

```
curl -s -X GET "${FILES_BASE}/api/v1/journal" \
  -H "Content-Type: application/json"
```

Supports cursor-based pagination via `after_id`:

```
curl -s -X GET "${FILES_BASE}/api/v1/journal?after_id=entry-12345" \
  -H "Content-Type: application/json"
```

#### 6.2 Flush Journal

```
curl -s -X POST "${FILES_BASE}/api/v1/journal/flush" \
  -H "Content-Type: application/json"
```

Forces all pending journal entries to be written and fsynced to disk. Returns 200 with `flushed=true` if all entries were durably persisted, or 503 with `flushed=false` if flush failed.

#### 6.3 Journal Statistics

```
curl -s -X GET "${FILES_BASE}/api/v1/journal/stats" \
  -H "Content-Type: application/json"
```

Returns storage statistics for the journal system including entry counts, blob storage usage, writer health, and pruning info.

---

### 7. Health and Version

#### 7.1 Health Check

```
curl -s -X GET "${FILES_BASE}/api/v1/files/health" \
  -H "Content-Type: application/json"
```

Returns service identity, build and start timestamps, resource usage, and caller metadata.

#### 7.2 Version

```
curl -s -X GET "${FILES_BASE}/api/v1/version" \
  -H "Content-Type: application/json"
```

Returns the current API version and server information.

---

## Advanced Operations

### 8. Multi-Step Workflow: Full Backend Lifecycle

This workflow demonstrates connecting a cloud backend, testing it, mounting it, verifying files, and cleaning up.

**Step 1: Connect S3 Backend**

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/s3" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "AWS",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE-WF8",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY-WF8",
    "region": "us-east-1",
    "endpoint": ""
  }'
```

Save the returned backend ID for subsequent steps.

**Step 2: Verify Connection**

```
curl -s -X GET "${FILES_BASE}/api/v1/backends/{backend-id}/test" \
  -H "Content-Type: application/json"
```

Confirm the test returns success before proceeding.

**Step 3: Create Persistent Mount**

```
curl -s -X POST "${FILES_BASE}/api/v1/mounts" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "{backend-id}",
    "mount_point": "/mnt/my-s3",
    "label": "production-data"
  }'
```

**Step 4: List Files via Mount**

```
curl -s -X GET "${FILES_BASE}/api/v1/files/mnt/my-s3" \
  -H "Content-Type: application/json"
```

**Step 5: Upload File to Backend**

```
curl -s -X PUT "${FILES_BASE}/api/v1/files/mnt/my-s3/data/report.pdf" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./report.pdf
```

**Step 6: Verify Upload with stat**

```
curl -s -X GET "${FILES_BASE}/api/v1/files/stat/mnt/my-s3/data/report.pdf" \
  -H "Content-Type: application/json"
```

**Step 7: Rotate Credentials When Needed**

```
curl -s -X PUT "${FILES_BASE}/api/v1/backends/{backend-id}" \
  -H "Content-Type: application/json" \
  -d '{
    "access_key_id": "NEW-KEY-ID",
    "secret_access_key": "NEW-SECRET-KEY"
  }'
```

**Step 8: Cleanup — Remove Mount and Backend**

```
# Remove mount first
curl -s -X DELETE "${FILES_BASE}/api/v1/mounts/{mount-id}" \
  -H "Content-Type: application/json"

# Then remove backend
curl -s -X DELETE "${FILES_BASE}/api/v1/backends/{backend-id}" \
  -H "Content-Type: application/json"
```

---

### 9. Multi-Step Workflow: Archive Processing Pipeline

Extract, inspect, and selectively process archive contents.

**Step 1: Preview Archive Before Extraction**

```
curl -s -X GET "${FILES_BASE}/backups/project-bundle.tar.gz?preview" \
  -H "Content-Type: application/json"
```

**Step 2: Extract Only Configuration Files**

```
curl -s -X GET "${FILES_BASE}/backups/project-bundle.tar.gz?extract=config/" \
  -H "Content-Type: application/json"
```

**Step 3: View a Specific File Without Extracting**

```
curl -s -X GET "${FILES_BASE}/backups/project-bundle.tar.gz?view_file=config/settings.json" \
  -H "Content-Type: application/json"
```

**Step 4: Extract Single File to Specific Location**

```
curl -s -X GET "${FILES_BASE}/backups/project-bundle.tar.gz?extract_file=src/app.ts" \
  -H "Content-Type: application/json"
```

**Step 5: Monitor Extraction Progress**

```
curl -s -X GET "${FILES_BASE}/api/v1/extractions" \
  -H "Content-Type: application/json"
```

**Step 6: Check Extraction History**

```
curl -s -X GET "${FILES_BASE}/?extraction_history" \
  -H "Content-Type: application/json"
```

---

### 10. Multi-Step Workflow: File Search and Bulk Operations

Search across files and perform batch operations.

**Step 1: Glob Search for All Log Files**

```
curl -s -X GET "${FILES_BASE}/api/v1/files/glob/var/log/**/*.log" \
  -H "Content-Type: application/json"
```

**Step 2: Grep for Errors Across All Logs**

```
curl -s -X GET "${FILES_BASE}/api/v1/files/grep/var/log?pattern=ERROR&glob=*.log" \
  -H "Content-Type: application/json"
```

**Step 3: Archive Matching Directory as ZIP**

```
curl -s -X GET "${FILES_BASE}/var/log?zip" \
  -H "Content-Type: application/json" \
  -o logs-backup.zip
```

**Step 4: Upload ZIP to Remote Backend**

```
curl -s -X PUT "${FILES_BASE}/api/v1/files/backups/logs-backup.zip?backend=my-s3-bucket" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./logs-backup.zip
```

**Step 5: Verify Upload on Remote**

```
curl -s -X GET "${FILES_BASE}/api/v1/files/stat/backups/logs-backup.zip?backend=my-s3-bucket" \
  -H "Content-Type: application/json"
```

---

### 11. Multi-Step Workflow: Encrypted Storage Chain

Combine utility backends for layered storage.

**Step 1: Connect Base Storage (S3)**

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/s3" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "AWS",
    "access_key_id": "AKIAIOSFODNN7EXAMPLE-WF11",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY-WF11",
    "region": "us-east-1",
    "endpoint": ""
  }'
```

Note the returned backend ID as `{s3-backend-id}`.

**Step 2: Layer Encryption on Top**

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/crypt" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "{s3-backend-id}:secure-data",
    "password": "my-strong-encryption-passphrase",
    "password2": "my-secondary-passphrase"
  }'
```

Note the returned backend ID as `{crypt-backend-id}`.

**Step 3: Add Caching Layer**

```
curl -s -X POST "${FILES_BASE}/api/v1/backends/cache" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "{crypt-backend-id}:"
  }'
```

**Step 4: Mount the Final Composite**

```
curl -s -X POST "${FILES_BASE}/api/v1/mounts" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "{cache-backend-id}",
    "mount_point": "/mnt/encrypted-cached",
    "label": "secure"
  }'
```

**Step 5: Test the Chain**

```
# Write encrypted file
curl -s -X PUT "${FILES_BASE}/api/v1/files/mnt/encrypted-cached/secret.txt" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./secret.txt

# Read it back (transparently decrypted)
curl -s -X GET "${FILES_BASE}/api/v1/files/mnt/encrypted-cached/secret.txt" \
  -H "Content-Type: application/json"
```

---

### 12. Error Recovery Patterns

#### 12.1 Retry Failed Backend Connection

```
# Step 1: Test connection to diagnose issue
curl -s -X GET "${FILES_BASE}/api/v1/backends/{id}/test" \
  -H "Content-Type: application/json"

# Step 2: If credentials expired, rotate them
curl -s -X PUT "${FILES_BASE}/api/v1/backends/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "{\"access_token\":\"new-oauth-token\",\"token_type\":\"Bearer\",\"refresh_token\":\"new-refresh\",\"expiry\":\"2025-12-01T00:00:00Z\"}"
  }'

# Step 3: Re-test connection
curl -s -X GET "${FILES_BASE}/api/v1/backends/{id}/test" \
  -H "Content-Type: application/json"
```

#### 12.2 Force Journal Flush After Bulk Operations

```
# Perform bulk file operations
# ...

# Force all journal entries to disk
curl -s -X POST "${FILES_BASE}/api/v1/journal/flush" \
  -H "Content-Type: application/json"

# Verify flush succeeded
curl -s -X GET "${FILES_BASE}/api/v1/journal/stats" \
  -H "Content-Type: application/json"
```

#### 12.3 Recover from Interrupted Download

```
# Check download status
curl -s -X GET "${FILES_BASE}/api/v1/downloads" \
  -H "Content-Type: application/json"

# Re-initiate download if needed
curl -s -X GET "${FILES_BASE}/downloads?url=https://example.com/large-file.zip" \
  -H "Content-Type: application/json"
```

---

### 13. Batch Operations

#### 13.1 Create Directory Structure

```
# Create nested directories one at a time
curl -s -X POST "${FILES_BASE}/api/v1/files/projects/app-2025/src" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "mkdir"
  }'

curl -s -X POST "${FILES_BASE}/api/v1/files/projects/app-2025/tests" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "mkdir"
  }'

curl -s -X POST "${FILES_BASE}/api/v1/files/projects/app-2025/docs" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "mkdir"
  }'
```

#### 13.2 Bulk File Upload Pattern

```
# Upload multiple files
for file in src/*.ts; do
  curl -s -X PUT "${FILES_BASE}/api/v1/files/projects/app-2025/${file}" \
    -H "Content-Type: application/octet-stream" \
    --data-binary "@${file}"
done
```

#### 13.3 Verify All Backends Are Healthy

```
# Get all backend IDs
BACKENDS=$(curl -s -X GET "${FILES_BASE}/api/v1/backends" \
  -H "Content-Type: application/json")

# Test each backend (parse IDs from response and test)
# Implementation depends on your shell tooling
```

---

## Quick Reference

### Endpoint Groups Summary

| Group | Base Path | Methods | Count |
|-------|-----------|---------|-------|
| Files (v1) | `/api/v1/files/{path}` | GET, POST, PUT, PATCH, DELETE | 15 |
| Files (root) | `/{path}` | GET, PUT, PATCH, DELETE, HEAD, OPTIONS | 12 |
| Backends | `/api/v1/backends` | GET, POST, PUT, DELETE | 68 |
| Mounts | `/api/v1/mounts` | GET, POST, PATCH, DELETE | 5 |
| Journal | `/api/v1/journal` | GET, POST | 3 |
| Downloads | `/api/v1/downloads` | GET | 3 |
| Extractions | `/api/v1/extractions` | GET | 4 |
| Archives | `/{archive}?extract` etc. | GET | 4 |
| Health | `/api/v1/files/health` | GET | 1 |
| Version | `/api/v1/version` | GET | 1 |
| Image | `/{image}?thumbnail` | GET | 1 |
| Remote | `/{path}?type=*` | GET, PUT | 6 |

### Files v1 Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/files/{path}` | List directory or download file |
| POST | `/api/v1/files/{path}` | Create directory, extract, download URL, move, copy |
| PUT | `/api/v1/files/{path}` | Upload file |
| PATCH | `/api/v1/files/{path}` | Modify properties, rename, move |
| DELETE | `/api/v1/files/{path}` | Delete file or directory |
| PUT | `/api/v1/files/append/{path}` | Append to file |
| PATCH | `/api/v1/files/chmod/{path}` | Change permissions (Unix) |
| PATCH | `/api/v1/files/chown/{path}` | Change ownership (Unix) |
| POST | `/api/v1/files/copy/{path}` | Copy file or directory |
| POST | `/api/v1/files/move/{path}` | Move or rename |
| GET | `/api/v1/files/glob/{path}` | Glob pattern search |
| GET | `/api/v1/files/grep/{path}` | Regex content search |
| GET | `/api/v1/files/realpath/{path}` | Resolve canonical path |
| GET | `/api/v1/files/stat/{path}` | Get file metadata |
| GET | `/api/v1/files/health` | Service health check |

### Root-Level File Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/{path}` | List directory or download file |
| PUT | `/{path}` | Upload file |
| PATCH | `/{path}` | Modify properties |
| DELETE | `/{path}` | Delete file or directory |
| HEAD | `/{path}` | Get file metadata headers |
| OPTIONS | `/{path}` | WebDAV capability discovery |
| PUT | `/{path}?touch` | Create empty file or update mtime |
| GET | `/{path}?type=ftp` | Access FTP files |
| GET | `/{path}?type=git` | Access Git repository files |
| GET | `/{path}?type=s3` | Access S3 files |
| GET | `/{path}?type=ssh` | Access SSH server files |
| PUT | `/{path}?type=ssh` | Upload to SSH server |
| GET | `/{path}?type=webdav` | Access WebDAV files |

### Archive Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/{archive}?extract` | Extract archive |
| GET | `/{archive}?extract_file` | Extract single file from archive |
| GET | `/{archive}?preview` | List or read archive contents |
| GET | `/{archive}?view_file` | Read single file from archive |
| GET | `/{directory}?zip` | Create ZIP of directory |
| GET | `/{image}?thumbnail` | Image processing |
| GET | `/{directory}?download` | Download from remote URL |
| GET | `/{directory}?downloads` | Check download progress |
| GET | `/{directory}?q` | Search files |
| GET | `/?download_history` | Download history |
| GET | `/?extraction_history` | Extraction history |
| GET | `/?extractions` | Active extractions |

### Backend Management Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/backends` | List all backends |
| GET | `/api/v1/backends/{id}` | Get backend details |
| PUT | `/api/v1/backends/{id}` | Rotate credentials |
| DELETE | `/api/v1/backends/{id}` | Remove backend |
| GET | `/api/v1/backends/{id}/test` | Test connection |
| POST | `/api/v1/backends/{type}` | Connect new backend (62 types) |

### Mount Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/mounts` | List all mounts |
| POST | `/api/v1/mounts` | Create FUSE mount |
| GET | `/api/v1/mounts/{id}` | Get mount details |
| PATCH | `/api/v1/mounts/{id}` | Update VFS config |
| DELETE | `/api/v1/mounts/{id}` | Remove mount |

### Journal Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/journal` | Query mutation entries |
| POST | `/api/v1/journal/flush` | Force flush to disk |
| GET | `/api/v1/journal/stats` | Storage statistics |

### System Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/v1/version` | API version info |

### Essential Parameters

| Endpoint Pattern | Key Parameters |
|-----------------|----------------|
| `/api/v1/files/glob/{path}` | glob pattern in path (e.g., `**/*.ts`) |
| `/api/v1/files/grep/{path}` | `?pattern=REGEX&glob=*.ext` |
| `/api/v1/files/chmod/{path}` | `?chmod=755` |
| `/api/v1/files/chown/{path}` | `?chown=user:group` |
| `/api/v1/files/copy/{path}` | JSON body `dest`, `?overwrite=true` |
| `/api/v1/files/move/{path}` | JSON body `dest` |
| `/api/v1/mounts` | `?label=filter` for listing |
| `/api/v1/journal` | `?after_id=cursor` for pagination |
| `/{archive}?extract` | `?extract=path` for selective extraction |
| `/{archive}?preview` | `?preview=path` to read specific file |
| `/{directory}?q` | `?q=searchterm&json=true` |
| `/{image}?thumbnail` | Format conversion and resize params |

### Response Formats

| Endpoint | Default Format | Notes |
|----------|---------------|-------|
| `GET /api/v1/files/{path}` (directory) | JSON array | File metadata objects |
| `GET /api/v1/files/{path}` (file) | Binary download | File content |
| `GET /api/v1/files/stat/{path}` | JSON object | Detailed metadata |
| `GET /api/v1/files/glob/{path}` | JSON array | Sorted file metadata |
| `GET /api/v1/files/grep/{path}` | JSON array | Matching lines with context |
| `GET /api/v1/backends` | JSON array | Backend summaries |
| `GET /api/v1/mounts` | JSON array | Mount configurations |
| `GET /api/v1/journal` | JSON array | Mutation entries |
| `GET /api/v1/version` | JSON object | Version and build info |
| `GET /api/v1/files/health` | JSON object | Health status |
| `GET /{path}` (directory) | HTML | Use `?json` for JSON |
| `GET /{directory}?q` | HTML | Use `?json` for JSON |

### All Supported Backend Types (61)

```
alias, azureblob, azurefiles, b2, box, cache, chunker, cloudinary,
combine, compress, crypt, drive, dropbox, fichier, filefabric,
filescom, ftp, gofile, google-cloud-storage, google-photos, hasher,
hdfs, hidrive, http, iclouddrive, imagekit, internetarchive,
jottacloud, koofr, linkbox, local, mailru, mega, memory, netstorage,
onedrive, opendrive, oracleobjectstorage, pcloud, pikpak, pixeldrain,
premiumizeme, protondrive, putio, qingstor, quatrix, s3, seafile,
sftp, sharefile, sia, smb, storj, sugarsync, swift,
ulozto, union, uptobox, webdav, yandex, zoho
```

### Complete Endpoint Count Verification

| Category | Endpoint Count |
|----------|---------------|
| Root-level file operations | 24 |
| Backend management (list/get/update/delete/test) | 6 |
| Backend creation (POST) | 61 |
| Files v1 API | 15 |
| Downloads | 1 |
| Extractions | 1 |
| Journal | 3 |
| Mounts | 5 |
| System | 1 |
| **Total** | **117** |