# File Operations

**Page:** api/files/file-operations

[Download Raw Markdown](./api/files/file-operations.md)

---

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



File operations provide a comprehensive set of endpoints for managing files and directories — uploading, modifying, deleting, searching, and inspecting them. Use these endpoints to integrate file management directly into your applications, with support for both local storage and remote cloud backends.

## Searching & Discovery

### `GET /{directory}?q`

Search for files matching a query string. Returns HTML by default, or JSON when `?json` is supplied. Matches are case-insensitive filename matches.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `directory` | path | string | Yes | Directory to search within |
| `q` | query | string | Yes | Search query (case-insensitive filename match) |
| `json` | query | string | No | Return JSON format instead of HTML |



```bash
curl -X GET "https://api.example.com/documents?q=report&json"
```


```typescript
const results = await client.files.search({
  directory: "documents",
  q: "report",
  json: ""
});
```


```json
{
  "allow_archive": true,
  "allow_delete": true,
  "allow_search": true,
  "allow_upload": true,
  "auth": true,
  "dir_exists": true,
  "href": "/documents",
  "kind": "Index",
  "paths": [
    {
      "mtime": 1718400000000,
      "name": "Q2-report.pdf",
      "path_type": "File",
      "revisions": 3,
      "size": 248320
    },
    {
      "mtime": 1718313600000,
      "name": "monthly-reports",
      "path_type": "Dir",
      "revisions": null,
      "size": 12
    }
  ],
  "uri_prefix": "/documents/",
  "user": "user@example.com"
}
```


```json
{
  "error": "Search is not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SEARCH_FORBIDDEN` | Search operation not allowed | Server is not configured to allow file searching | Contact administrator to enable --allow-search flag |
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | User account does not have search permissions for this path | Contact administrator for search permissions or authenticate with different account |



### `GET /{image}?thumbnail`

Process and convert images on the fly. Supports JPEG, PNG, WebP, GIF, and BMP input/output, with resizing, quality control, blur, grayscale, and background color options. Works for both local files and all 60+ remote cloud storage backends.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `image` | path | string | Yes | Path to image file |
| `thumbnail` | query | string | Yes | Enable image processing |
| `format` | query | string | No | Output format (default: `jpeg`) — one of `jpeg`, `png`, `webp`, `gif`, `bmp` |
| `size` | query | string | No | Width×Height in pixels (max: 2000×2000) |
| `width` | query | integer | No | Width in pixels (height auto-calculated) |
| `height` | query | integer | No | Height in pixels (width auto-calculated) |
| `resize` | query | string | No | Resize mode: `fit` (preserve aspect, fit within), `fill` (exact size, crop), `cover` (cover area), `exact` (force dimensions) — default: `fit` |
| `quality` | query | string | No | Resize algorithm quality: `low` (box filter), `medium` (bilinear), `high` (Lanczos3) — default: `medium` |
| `q` | query | integer | No | JPEG/WebP quality (1-100, higher is better quality) — default: `85` |
| `blur` | query | number | No | Gaussian blur radius (0-50) |
| `grayscale` | query | string | No | Convert to grayscale/black-and-white |
| `bg` | query | string | No | Background color for transparency (hex RGB, e.g., `ffffff` for white) |



```bash
curl -X GET "https://api.example.com/photos/landscape.png?thumbnail=&width=800&format=webp&q=80" \
  -o landscape-800.webp
```


```typescript
const image = await client.files.images.process({
  image: "photos/landscape.png",
  thumbnail: "",
  format: "webp",
  width: 800,
  q: 80
});
```


```json
{
  "description": "Processed image returned as binary data with Content-Type matching the requested format. Cache-Control: public, max-age=3600"
}
```


```json
{
  "error": "Unsupported image format",
  "success": false
}
```



### `GET /api/v1/files/glob/{path}`

Find files and directories matching a glob pattern. Supports recursive patterns (`**/*.rs`), brace expansion (`{ts,tsx}`), character classes `[a-z]`, and standard wildcards (`*`). Returns file metadata sorted by modification time (newest first) by default. Respects `.gitignore` by default.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Directory path to search within |
| `pattern` | query | string | Yes | Glob pattern (e.g. `**/*.rs`, `src/**/*.{ts,tsx}`, `*.md`) |
| `max_results` | query | integer | No | Maximum entries to return — default: `1000` |
| `max_depth` | query | integer | No | Maximum directory recursion depth — default: `50` |
| `max_files_scanned` | query | integer | No | Maximum filesystem entries to scan — default: `100000` |
| `timeout` | query | integer | No | Search timeout in seconds — default: `30` |
| `no_ignore` | query | boolean | No | Bypass `.gitignore` filtering — default: `false` |
| `sort` | query | string | No | Sort results by: `mtime` (modification time), `name`, or `size` — default: `mtime` |
| `order` | query | string | No | Sort order. Default: `desc` for mtime, `asc` for name/size — one of `asc`, `desc` |



```bash
curl -X GET "https://api.example.com/api/v1/files/glob/src?pattern=**/*.ts&max_results=50"
```


```typescript
const results = await client.files.glob({
  path: "src",
  pattern: "**/*.ts",
  max_results: 50
});
```


```json
{
  "count": 2,
  "duration_ms": 47,
  "entries": [
    {
      "is_dir": false,
      "modified": 1718400000,
      "name": "src/index.ts",
      "size": 1842
    },
    {
      "is_dir": false,
      "modified": 1718313600,
      "name": "src/utils/helpers.ts",
      "size": 4096
    }
  ],
  "path": "src",
  "pattern": "**/*.ts",
  "total_scanned": 128,
  "truncated": false
}
```


```json
{
  "error": "Invalid glob pattern",
  "success": false
}
```


```json
{
  "error": "Search is not enabled on this server",
  "success": false
}
```


```json
{
  "error": "Path not found",
  "success": false
}
```


```json
{
  "error": "Too many concurrent searches",
  "success": false
}
```



### `GET /api/v1/files/grep/{path}`

Search file or directory contents using regex patterns. Powered by ripgrep with `.gitignore` support, binary file detection, and configurable limits. Returns matching lines with optional context.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File or directory path to search |
| `pattern` | query | string | Yes | Search pattern (regex by default, literal if `fixed_string=true`) |
| `ignore_case` | query | boolean | No | Case-insensitive matching — default: `false` |
| `fixed_string` | query | boolean | No | Treat pattern as literal string, not regex — default: `false` |
| `glob` | query | string | No | Filter files by glob pattern (e.g. `*.rs`, `*.{ts,tsx}`) |
| `context` | query | integer | No | Number of context lines before and after each match — default: `0` |
| `max_count` | query | integer | No | Maximum matches per file — default: `50` |
| `max_matches` | query | integer | No | Total maximum matches across all files — default: `500` |
| `max_depth` | query | integer | No | Maximum directory recursion depth — default: `50` |
| `max_filesize` | query | integer | No | Skip files larger than this (bytes) — default: `10485760` |
| `timeout` | query | integer | No | Search timeout in seconds — default: `30` |
| `no_ignore` | query | boolean | No | Bypass `.gitignore` filtering — default: `false` |



```bash
curl -X GET "https://api.example.com/api/v1/files/grep/src?pattern=TODO&context=2&max_count=20"
```


```typescript
const results = await client.files.grep({
  path: "src",
  pattern: "TODO",
  context: 2,
  max_count: 20
});
```


```json
{
  "duration_ms": 124,
  "matches": [
    {
      "column_byte": 4,
      "context_after": ["    return result;"],
      "context_before": ["function calculate() {"],
      "line": "    // TODO: handle edge case",
      "line_number": 42,
      "path": "src/utils/math.ts"
    }
  ],
  "path": "src",
  "pattern": "TODO",
  "total_files_matched": 1,
  "total_files_searched": 84,
  "total_matches": 1,
  "truncated": false
}
```


```json
{
  "error": "Invalid regex pattern",
  "success": false
}
```


```json
{
  "error": "Grep is not enabled on this server",
  "success": false
}
```


```json
{
  "error": "Path not found",
  "success": false
}
```


```json
{
  "error": "Too many concurrent searches",
  "success": false
}
```



### `GET /api/v1/files/realpath/{path}`

Resolve a file or directory path to its canonical absolute form by following all symbolic links and resolving all `.`/`..` segments. Equivalent to POSIX `realpath(3)` or Node.js `fs.realpath()`. The returned `real_path` is relative to the serve root. Returns 404 if the path does not exist, 400 for circular symlinks (ELOOP), and 403 if the resolved path escapes the serve root.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File or directory path to resolve |



```bash
curl -X GET "https://api.example.com/api/v1/files/realpath/docs/../README.md"
```


```typescript
const result = await client.files.realpath({
  path: "docs/../README.md"
});
```


```json
{
  "path": "docs/../README.md",
  "real_path": "/README.md"
}
```


```json
{
  "error": "Symlink loop detected",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_PATH` | Invalid path | Path contains invalid characters or traversal attempts | — |
| `ELOOP` | Symlink loop | Too many levels of symbolic links (circular chain) | — |
| `OPERATION_CONFLICT` | Operation conflict | Cannot combine realpath with other query operations | — |


```json
{
  "error": "Resolved path is outside serve root",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `PERMISSION_DENIED` | Permission denied | Insufficient permissions to access the path | — |
| `PATH_ESCAPE` | Path escapes root | Resolved canonical path is outside the serve root | — |


```json
{
  "error": "Path not found",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `PATH_NOT_FOUND` | Path not found | The path does not exist or contains a broken symlink | Verify the path exists and all symlinks in the chain are valid |



### `GET /api/v1/files/stat/{path}`

Get detailed metadata (`stat`) for a single file or directory without downloading content. Returns name, type, size, modification time, permissions, ownership, and symlink information.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File or directory path |



```bash
curl -X GET "https://api.example.com/api/v1/files/stat/README.md"
```


```typescript
const metadata = await client.files.stat({
  path: "README.md"
});
```


```json
{
  "group": "staff",
  "is_symlink": false,
  "mtime": 1718400000000,
  "name": "README.md",
  "owner": "user",
  "path": "README.md",
  "path_type": "File",
  "permissions": "644",
  "revisions": 5,
  "size": 4096,
  "symlink_target": null
}
```


```json
{
  "error": "File not found",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `FILE_NOT_FOUND` | File not found | The specified path does not exist | Verify the path is correct |



## File Operations

### `POST /api/v1/files/{path}`

Perform various file operations: create directory, extract archive, download from URL, move, or copy. Pass the operation as a query parameter.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Target file or directory path |
| `backend` | query | string | No | Backend ID for remote operations |
| `mkdir` | query | string | No | Create directory |
| `extract` | query | string | No | Extract archive. Empty value extracts all; non-empty value is a selective path to extract (e.g. `src/main.rs` or `lib/`) |
| `dest` | query | string | No | Destination directory name for extraction (default: archive name without extension) |
| `download_from` | query | string | No | Download file from remote URL |
| `move_to` | query | string | No | Move file/directory to destination path |
| `copy_to` | query | string | No | Copy file/directory to destination path |
| `overwrite` | query | string | No | Allow overwriting existing destination (for copy) — one of `true`, `false` |
| `owner` | query | string | No | Create-time owner for newly-created inodes as user[:group] or uid[:gid]. Requires --allow-chown and must resolve to an entry in --allowed-create-owners; refuses root (uid/gid 0). Absent → the server default create owner. Applies to mkdir/extract/download_from/copy_to. |



```bash
curl -X POST "https://api.example.com/api/v1/files/projects/new-app?mkdir="
```


```bash
curl -X POST "https://api.example.com/api/v1/files/downloads/release.tar.gz?extract="
```


```bash
curl -X POST "https://api.example.com/api/v1/files/data.csv?download_from=https://example.com/data.csv"
```


```typescript
// Create a directory
await client.files.operate({
  path: "projects/new-app",
  mkdir: ""
});

// Extract an archive
await client.files.operate({
  path: "downloads/release.tar.gz",
  extract: ""
});
```


```json
{
  "source": "/data/old.csv",
  "destination": "/data/new.csv",
  "success": true
}
```


```json
{
  "message": "Directory created",
  "success": true
}
```


```json
{
  "error": "Source file or directory not found",
  "success": false
}
```


```json
{
  "error": "Destination already exists",
  "success": false
}
```



### `POST /api/v1/files/copy/{path}`

Copy a file or directory to a new location. Supports recursive directory copy. Auto-creates parent directories at destination. Use `?overwrite=true` to replace existing destination.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Source file or directory path |
| `copy_to` | query | string | Yes | Destination path to copy the file/directory to |
| `overwrite` | query | string | No | Allow overwriting existing destination (default: false) — one of `true`, `false` |
| `owner` | query | string | No | Create-time owner (user[:group]/uid[:gid]) for newly-created copies. Requires --allow-chown + allowlist; refuses root. Overwritten existing files preserve their owner. Absent → server default. |



```bash
curl -X POST "https://api.example.com/api/v1/files/copy/src/index.ts?copy_to=backup/index.ts"
```


```typescript
const result = await client.files.copy({
  path: "src/index.ts",
  copy_to: "backup/index.ts"
});
```


```json
{
  "destination": "backup/index.ts",
  "source": "src/index.ts",
  "success": true
}
```


```json
{
  "error": "Copy operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `COPY_FORBIDDEN` | Copy not allowed | Server requires --allow-upload flag for copy operations | Contact administrator to enable --allow-upload flag |


```json
{
  "error": "Source file or directory not found",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SOURCE_NOT_FOUND` | Source not found | The source path does not exist | Verify the source path is correct |


```json
{
  "error": "Destination already exists",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DESTINATION_EXISTS` | Destination conflict | A file or directory already exists at the destination path | Use ?overwrite=true to replace or choose a different destination |



### `POST /api/v1/files/move/{path}`

Move or rename a file/directory to a new location. Works across directories. Auto-creates parent directories at destination. Requires both upload and delete permissions.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Source file or directory path |
| `move_to` | query | string | Yes | Destination path to move the file/directory to |
| `owner` | query | string | No | Create-time owner (user[:group]/uid[:gid]) for newly-created destination PARENT directories. Requires --allow-chown + --allowed-create-owners; refuses root. The moved inode itself preserves its existing owner. Absent → server default. |



```bash
curl -X POST "https://api.example.com/api/v1/files/move/draft.md?move_to=published/draft.md"
```


```typescript
const result = await client.files.move({
  path: "draft.md",
  move_to: "published/draft.md"
});
```


```json
{
  "destination": "published/draft.md",
  "source": "draft.md",
  "success": true
}
```


```json
{
  "error": "Move operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MOVE_FORBIDDEN` | Move not allowed | Server requires both --allow-upload and --allow-delete flags for move operations | Contact administrator to enable both flags |


```json
{
  "error": "Source file or directory not found",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `SOURCE_NOT_FOUND` | Source not found | The source path does not exist | Verify the source path is correct |


```json
{
  "error": "Destination already exists",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DESTINATION_EXISTS` | Destination conflict | A file or directory already exists at the destination path | Delete the existing file first or choose a different destination |



## Uploading & Appending

### `PUT /{path}`

Upload a file to the server. Creates new files or overwrites existing ones.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Destination file path |

#### Request Body

Sends the file content as `application/octet-stream` binary data.



```bash
curl -X PUT "https://api.example.com/uploads/report.pdf" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @report.pdf
```


```typescript
const result = await client.files.upload({
  path: "uploads/report.pdf",
  body: fileBuffer
});
```


```json
{
  "description": "File uploaded successfully"
}
```


```json
{
  "error": "Upload operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `UPLOAD_FORBIDDEN` | Upload operation not allowed | Server is not configured to allow file uploads | Contact administrator to enable --allow-upload flag |



### `PUT /{path}?touch`

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

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File path to touch |
| `touch` | query | string | Yes | Flag to indicate touch operation |



```bash
curl -X PUT "https://api.example.com/logs/today.txt?touch="
```


```typescript
await client.files.touch({
  path: "logs/today.txt",
  touch: ""
});
```


```json
{
  "description": "File created (did not exist)"
}
```


```json
{
  "description": "Modification time updated (file already existed)"
}
```


```json
{
  "error": "Cannot touch a directory",
  "success": false
}
```


```json
{
  "error": "Touch operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `TOUCH_FORBIDDEN` | Touch operation not allowed | Server is not configured to allow touch operations | Contact administrator to enable --allow-touch flag |



### `PUT /api/v1/files/{path}`

Upload a file to the server or to a remote backend. Use `?append` to append to an existing file instead of overwriting.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Destination file path |
| `backend` | query | string | No | Backend ID for remote upload |
| `append` | query | string | No | Append body to end of existing file (create if missing) instead of overwriting |
| `owner` | query | string | No | Create-time owner (user[:group]/uid[:gid]) for a newly-created file. Requires --allow-chown + --allowed-create-owners; refuses root. Overwrites/appends to an existing file preserve its owner. Absent → server default. |

#### Request Body

Sends the file content as `application/octet-stream` binary data.



```bash
curl -X PUT "https://api.example.com/api/v1/files/uploads/data.csv" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv
```


```typescript
const result = await client.files.put({
  path: "uploads/data.csv",
  body: fileBuffer
});
```


```json
{
  "new_size": 8192,
  "path": "logs/server.log",
  "success": true
}
```


```json
{
  "message": "File uploaded successfully",
  "path": "uploads/data.csv",
  "size": 4096,
  "success": true
}
```


```json
{
  "error": "Upload operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `UPLOAD_FORBIDDEN` | Upload operation not allowed | Server is not configured to allow file uploads | Contact administrator to enable --allow-upload flag |
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | User account does not have upload permissions for this path | Contact administrator for write permissions or authenticate with different account |



### `PUT /api/v1/files/append/{path}`

Append binary data to the end of an existing file. Creates the file if it does not exist. Auto-creates parent directories.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File path |
| `owner` | query | string | No | Create-time owner (user[:group]/uid[:gid]) when this append creates a new file. Requires --allow-chown + allowlist; refuses root. Absent → server default. |

#### Request Body

Sends the file content as `application/octet-stream` binary data.



```bash
curl -X PUT "https://api.example.com/api/v1/files/append/logs/server.log" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "New log line\n"
```


```typescript
const result = await client.files.append({
  path: "logs/server.log",
  body: Buffer.from("New log line\n")
});
```


```json
{
  "new_size": 12288,
  "path": "logs/server.log",
  "success": true
}
```


```json
{
  "error": "Upload operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `UPLOAD_FORBIDDEN` | Upload not allowed | Server is not configured to allow file uploads | Contact administrator to enable --allow-upload flag |



## Modifying Properties

### `PATCH /{path}`

Supports resumable uploads, appending to files, changing file permissions (Unix only), changing file ownership (Unix only), and renaming files or directories.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File or directory path |
| `X-Update-Range` | header | string | No | Set to `append` to append data to the end of the file. Perfect for logs and incremental writes. Example: `curl -X PATCH -H 'X-Update-Range: append' --data-binary @data.txt http://server/file.log` |

#### Request Body

The request body is one of:

- **ChmodRequest** (`{ "mode": "755" }`) — change file permissions
- **ChownRequest** (`{ "owner": "user", "group": "users" }`) — change file ownership
- **RenameRequest** (`{ "name": "new-filename.txt" }`) — rename file or directory
- **Binary `application/octet-stream`** — for resumable uploads or appending (use `X-Update-Range: append` header)



```bash
curl -X PATCH "https://api.example.com/script.sh" \
  -H "Content-Type: application/json" \
  -d '{"mode": "755"}'
```


```bash
curl -X PATCH "https://api.example.com/old-name.txt" \
  -H "Content-Type: application/json" \
  -d '{"name": "new-name.txt"}'
```


```bash
curl -X PATCH "https://api.example.com/logs/server.log" \
  -H "X-Update-Range: append" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "New log line\n"
```


```typescript
// Change permissions
await client.files.patch({
  path: "script.sh",
  data: { mode: "755" }
});

// Rename
await client.files.patch({
  path: "old-name.txt",
  data: { name: "new-name.txt" }
});
```


```json
{
  "description": "Operation successful"
}
```


```json
{
  "error": "Invalid permissions format",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_OPERATION` | Invalid operation | The requested operation is not valid or parameters are malformed | Check request format and ensure valid operation parameters |
| `INVALID_PERMISSIONS_FORMAT` | Invalid permissions format | Chmod mode must be valid octal format (e.g., 755, 644) | Use valid octal permission format |


```json
{
  "error": "Operation not allowed on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `OPERATION_FORBIDDEN` | Operation not allowed | Server is not configured to allow this operation (chmod/chown/rename/upload) | Contact administrator to enable appropriate flags |
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | User account does not have permissions for this operation | Contact administrator for required permissions |


```json
{
  "error": "A file with the target name already exists",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `FILE_EXISTS` | File already exists | Cannot rename - a file or directory with the target name already exists | Choose a different name or delete the existing file first |
| `NAME_CONFLICT` | Name conflict | The target filename conflicts with an existing entry | Use a unique filename or remove conflicting file |



### `PATCH /api/v1/files/{path}`

Modify file properties or move/rename via REST API v1. Supports `chmod` (`?chmod=755`), `chown` (`?chown=user:group`), rename (JSON body with `name`), and cross-directory move (JSON body with `move_to`).

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File path |
| `backend` | query | string | No | Backend ID for remote file operations |
| `chmod` | query | string | No | Set file permissions using octal mode value (e.g., `?chmod=755`) |
| `chown` | query | string | No | Set file ownership (e.g., `?chown=user:group` or `?chown=user`) |
| `owner` | query | string | No | Create-time owner (user[:group]/uid[:gid]) for newly-created destination parent directories on a JSON-body move_to. Requires --allow-chown + --allowed-create-owners; cannot be root. The moved item keeps its own owner. Absent → server default. |

#### Request Body

The request body is one of:

- **MoveRequest** (`{ "move_to": "/new/dir/file.txt" }`) — move file to a new path
- **RenameRequest** (`{ "name": "new-filename.txt" }`) — rename file in place



```bash
curl -X PATCH "https://api.example.com/api/v1/files/script.sh?chmod=755"
```


```bash
curl -X PATCH "https://api.example.com/api/v1/files/script.sh?chown=user:staff"
```


```bash
curl -X PATCH "https://api.example.com/api/v1/files/old/path.txt" \
  -H "Content-Type: application/json" \
  -d '{"move_to": "/new/dir/path.txt"}'
```


```typescript
// Change permissions via query
await client.files.patchApi({
  path: "script.sh",
  chmod: "755"
});

// Move via body
await client.files.patchApi({
  path: "old/path.txt",
  data: { move_to: "/new/dir/path.txt" }
});
```


```json
{
  "mode": "755",
  "path": "script.sh",
  "success": true
}
```


```json
{
  "error": "Invalid chmod mode",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_MODE` | Invalid chmod mode | The chmod mode value is not valid octal notation | Use octal notation like 755 or 644 (max 7777) |
| `INVALID_OWNER` | Invalid owner or group | The specified user or group could not be resolved | Verify the username/group exists on the system |


```json
{
  "error": "chmod not allowed on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CHMOD_FORBIDDEN` | Chmod not allowed | Server is not configured to allow chmod operations | Contact administrator to enable --allow-chmod flag |
| `CHOWN_FORBIDDEN` | Chown not allowed | Server is not configured to allow chown operations | Contact administrator to enable --allow-chown flag |


```json
{
  "error": "File or directory not found",
  "success": false
}
```


```json
{
  "error": "Destination already exists",
  "success": false
}
```



### `PATCH /api/v1/files/chmod/{path}`

Change file or directory permissions using octal mode (Unix only). Pass the mode value in the `chmod` query parameter, e.g., `?chmod=755`.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File or directory path |
| `chmod` | query | string | Yes | Octal permission mode (e.g., `755`, `644`, `0755`) |



```bash
curl -X PATCH "https://api.example.com/api/v1/files/chmod/script.sh?chmod=755"
```


```typescript
const result = await client.files.chmod({
  path: "script.sh",
  chmod: "755"
});
```


```json
{
  "mode": "755",
  "path": "script.sh",
  "success": true
}
```


```json
{
  "error": "Invalid chmod mode",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_MODE` | Invalid chmod mode | The mode value is not valid octal notation | Use octal notation like 755 or 644 (max 7777) |
| `UNIX_ONLY` | Unix only | chmod is only supported on Unix systems | Use a Unix-based server |


```json
{
  "error": "chmod not allowed on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CHMOD_FORBIDDEN` | Chmod not allowed | Server is not configured to allow chmod operations | Contact administrator to enable --allow-chmod flag |


```json
{
  "error": "File or directory not found",
  "success": false
}
```



### `PATCH /api/v1/files/chown/{path}`

Change file or directory ownership (Unix only). Pass `owner:group` in the `chown` query parameter, e.g., `?chown=user:group`. Group is optional.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | File or directory path |
| `chown` | query | string | Yes | Owner and optional group (e.g., `user:group`, `user`, `:group`, or `UID:GID`) |



```bash
curl -X PATCH "https://api.example.com/api/v1/files/chown/data.csv?chown=app:staff"
```


```typescript
const result = await client.files.chown({
  path: "data.csv",
  chown: "app:staff"
});
```


```json
{
  "group": "staff",
  "owner": "app",
  "path": "data.csv",
  "success": true
}
```


```json
{
  "error": "Invalid owner or group",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `INVALID_OWNER` | Invalid owner | The specified user could not be resolved | Verify the username or UID exists on the system |
| `INVALID_GROUP` | Invalid group | The specified group could not be resolved | Verify the group name or GID exists on the system |
| `UNIX_ONLY` | Unix only | chown is only supported on Unix systems | Use a Unix-based server |


```json
{
  "error": "chown not allowed on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `CHOWN_FORBIDDEN` | Chown not allowed | Server is not configured to allow chown operations | Contact administrator to enable --allow-chown flag |


```json
{
  "error": "File or directory not found",
  "success": false
}
```



## Deletion

### `DELETE /{path}`

Permanently delete a file or directory. Recursive — deleting a directory removes its contents.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Path to file or directory to delete |



```bash
curl -X DELETE "https://api.example.com/old/draft.txt"
```


```typescript
const result = await client.files.deleteRecursive({
  path: "old/draft.txt"
});
```


```json
{
  "message": "File deleted successfully",
  "success": true
}
```


```json
{
  "error": "Delete operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DELETE_FORBIDDEN` | Delete operation not allowed | Server is not configured to allow file deletion | Contact administrator to enable --allow-delete flag |


```json
{
  "error": "File or directory not found",
  "success": false
}
```



### `DELETE /api/v1/files/{path}`

Delete a file or directory from the server or a remote backend. Supports a `backend` query parameter to target a specific cloud storage backend.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `path` | path | string | Yes | Path to file or directory to delete |
| `backend` | query | string | No | Backend ID for remote file deletion |



```bash
curl -X DELETE "https://api.example.com/api/v1/files/old/draft.txt"
```


```typescript
const result = await client.files.delete({
  path: "old/draft.txt"
});
```


```json
{
  "message": "File deleted successfully",
  "success": true
}
```


```json
{
  "error": "Delete operations are not enabled on this server",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DELETE_FORBIDDEN` | Delete operation not allowed | Server is not configured to allow file deletion | Contact administrator to enable --allow-delete flag |
| `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | User account does not have delete permissions for this path | Contact administrator for write permissions |


```json
{
  "error": "File or directory not found",
  "success": false
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `FILE_NOT_FOUND` | File or directory not found | The specified path does not exist in storage or backend | Verify the path is correct and the file exists |