# CasaOS APIs for Batch Operations and File Management: Complete REST API Reference

> Explore CasaOS APIs for batch operations and file management. Discover RESTful endpoints for bulk actions and individual file handling with Go and Echo framework.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: api-reference
- Published: 2026-06-26

---

**CasaOS exposes RESTful HTTP endpoints under `/api/v1/batch` for bulk file operations and `/api/v1/file` for individual file management, implemented in Go using the Echo framework with support for chunked uploads, queue-based task management, and thumbnail generation.**

CasaOS provides a comprehensive REST API for managing files and performing batch operations on Linux-based home servers. The API routes are defined in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go) and [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go), utilizing the Echo web framework to handle everything from single-file deletions to asynchronous batch copying and moving tasks. These endpoints enable developers to integrate CasaOS file management capabilities into third-party applications or automation scripts.

## Batch Operations API

The batch operations API, mounted under `/api/v1/batch` in [`route/v1.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1.go), handles bulk actions on multiple files or directories through a centralized task queue. According to the CasaOS source code, these endpoints leverage the global `service.FileQueue` to track long-running operations while providing real-time status updates via the notification service.

### Delete Multiple Files

To delete several files or directories simultaneously, send a **DELETE** request to `/api/v1/batch` with a JSON array of absolute paths. The `DeleteFile` function in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go) processes this request:

```bash
curl -X DELETE "http://<host>/api/v1/batch" \
     -H "Authorization: Bearer <api-key>" \
     -H "Content-Type: application/json" \
     -d '["/share/docs/report.pdf","/share/tmp/old.log"]'

```

### Create Batch Tasks (Copy, Move, or Rename)

Long-running batch operations like copying or moving directories are created via **POST** `/api/v1/batch/task`. This endpoint accepts a JSON payload describing the source paths, destination, and operation type, handled by the `PostOperateFileOrDir` function:

```bash
curl -X POST "http://<host>/api/v1/batch/task" \
     -H "Authorization: Bearer <api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "src": ["/share/photos/2023/"],
           "dst": "/share/backup/photos/",
           "op": "copy"
         }'

```

### Cancel Running Batch Tasks

To abort a queued or in-progress operation, send a **DELETE** request to `/api/v1/batch/{id}/task`. This calls `DeleteOperateFileOrDir`, removes the entry from `service.FileQueue`, and triggers a notification update:

```bash
curl -X DELETE "http://<host>/api/v1/batch/12345/task" \
     -H "Authorization: Bearer <api-key>"

```

### Download Files and Archives

The batch endpoint also handles downloads via **GET** `/api/v1/batch`, supporting both single file downloads and ZIP archive generation for multiple files through the `GetDownloadFile` handler.

## File Management API

Individual file operations are available under `/api/v1/file` and `/api/v2/file`, providing granular control over content updates, uploads, and metadata retrieval.

### Delete Individual Files

The `DeleteFile` function in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go) handles **DELETE** requests to `/api/v1/file/delete`, accepting a JSON array of paths similar to the batch endpoint but optimized for single operations.

### Update File Content

Modify existing files in-place using **PUT** `/api/v1/file/update`, which calls `PutFileContent` and expects a JSON body with `path` and `content` fields:

```json
{
  "path": "/a/b.txt",
  "content": "new file content here"
}

```

### Image Retrieval and Thumbnails

Retrieve images or their thumbnails via **GET** `/api/v1/file/image` using the `GetFileImage` function. The `type` parameter accepts `thumbnail` for preview generation:

```bash
curl -X GET "http://<host>/api/v1/file/image?path=/share/pics/cat.jpg&type=thumbnail" \
     -H "Authorization: Bearer <api-key>" \
     --output cat_thumb.jpg

```

### Chunked Upload API

Large file uploads are handled by the v2 API in [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go). The process involves multipart form data posted to **POST** `/api/v2/file/upload`, managed by the `PostUploadFile` function:

```bash

# First chunk

curl -X POST "http://<host>/api/v2/file/upload" \
     -F "path=/share/uploads" \
     -F "chunkNumber=1" \
     -F "chunkSize=1048576" \
     -F "currentChunkSize=1048576" \
     -F "totalChunks=5" \
     -F "totalSize=5242880" \
     -F "identifier=abc123" \
     -F "filename=video.mp4" \
     -F "relativePath=video.mp4" \
     -F "file=@chunk1.bin"

```

Repeat with `chunkNumber=2` through `5`. The server assembles the file once all chunks are received.

### Directory Operations

Directory management endpoints are grouped under `/api/v1/folder` in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go):

- **GET** `/folder/dirpath` - List contents via `DirPath`
- **POST** `/folder` - Create directories via `MkdirAll`
- **PUT** `/folder/name` - Rename via `RenamePath`
- **GET** `/folder/size` - Calculate size via `GetSize`
- **GET** `/folder/count` - Count entries via `GetFileCount`

## Route Registration and Architecture

All v1 routes are registered in [`route/v1.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1.go) within dedicated Echo groups. The `v1BatchGroup` handles `/batch` paths while `v1FileGroup` and `v1FolderGroup` manage file operations:

```go
v1BatchGroup := v1Group.Group("/batch")
{
    v1BatchGroup.DELETE("", v1.DeleteFile)
    v1BatchGroup.DELETE("/:id/task", v1.DeleteOperateFileOrDir)
    v1BatchGroup.POST("/task", v1.PostOperateFileOrDir)
    v1BatchGroup.GET("", v1.GetDownloadFile)
}

```

The v2 chunked upload resides in [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go) as a separate implementation. Supporting utilities for file size calculation and image processing are located in [`model/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/model/file.go), while [`service/notify.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/notify.go) handles UI notifications for batch operation status changes.

## Summary

- **Batch operations** use `/api/v1/batch` endpoints for delete, copy, move, and download operations
- The `service.FileQueue` manages asynchronous task execution and cancellation via `DeleteOperateFileOrDir`
- **File management** spans `/api/v1/file` for content updates and `/api/v1/folder` for directory operations
- **Chunked uploads** are implemented in v2 API at `/api/v2/file/upload` using `PostUploadFile`
- Key implementation files include [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go), [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go), and [`service/file_upload.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/file_upload.go)

## Frequently Asked Questions

### What authentication method does CasaOS use for these APIs?

CasaOS API endpoints require authentication via the `ApiKeyAuth` security scheme. Include the API key in the `Authorization` header as a Bearer token: `Authorization: Bearer <api-key>`. All endpoints in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go) and [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go) enforce this authentication.

### Can I cancel a long-running batch operation?

Yes. Batch tasks can be cancelled by sending a DELETE request to `/api/v1/batch/{id}/task`. This endpoint calls `DeleteOperateFileOrDir` in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go), removes the task from the `service.FileQueue`, and notifies the UI of the cancellation status through the notification service.

### How does CasaOS handle large file uploads?

Large files are uploaded via the v2 API using chunked multipart uploads to `/api/v2/file/upload`. The client sends file chunks sequentially with metadata including `chunkNumber`, `totalChunks`, and `identifier`, which the server reassembles upon completion according to the implementation in [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go).

### Where are the API route handlers defined in the source code?

Route handlers are defined in [`route/v1/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1/file.go) for batch and file operations, [`route/v2/file.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2/file.go) for chunked uploads, and registered in [`route/v1.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v1.go) where the Echo router groups (`v1BatchGroup`, `v1FileGroup`, `v1FolderGroup`) are configured. The batch queue implementation resides in [`service/file_upload.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/file_upload.go).